# Build Mcp Use Server

> Use if building TypeScript MCP servers with mcp-use/server — server.tool, ctx.auth, transports.

- **Type:** Skill
- **Install:** `agentstack add skill-yigitkonur-skills-by-yigitkonur-build-mcp-use-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yigitkonur](https://agentstack.voostack.com/s/yigitkonur)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** https://github.com/yigitkonur/skills-by-yigitkonur/tree/main/plugins/build-mcp-use-server/skills/build-mcp-use-server

## Install

```sh
agentstack add skill-yigitkonur-skills-by-yigitkonur-build-mcp-use-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Build mcp-use Server

Server-side mechanics for `mcp-use/server` TypeScript MCP servers. This skill owns API surface; sister skills own structure, clients, agents, and raw SDK.

## When to use this skill

Trigger when the target code or request involves any of these:

- *Imports from `mcp-use/server` (`MCPServer`, `text`, `object`, `mix`, `error`, `widget`, `Logger`).*
- *Defining or refining `server.tool()`, `server.resource()`, `server.prompt()`, `server.uiResource()` with Zod schemas.*
- *Server-side `ctx` work — `ctx.auth`, `ctx.elicit()`, `ctx.sample()`, `ctx.notify()`, `ctx.client.can()`, `ctx.client.supportsApps()`.*
- *Configuring transports (Streamable HTTP, stateless, stdio), session stores, OAuth (DCR or proxy), CORS, allowedOrigins, DNS rebinding.*
- *MCP Apps / ChatGPT Apps widgets — `widgetMetadata`, `text/html;profile=mcp-app`, `text/html+skybridge`, `McpUseProvider`, `useCallTool`, `useWidget`, CSP.*
- *Running `mcp-use dev`, `mcp-use build`, `mcp-use start`, `mcp-use deploy`, `mcp-use generate-types`, or debugging via Inspector / curl handshake on `/mcp`.*
- *Hardening for production: health/readiness routes, graceful shutdown, rate limits, deploy to mcp-use Cloud, Vercel, Cloud Run, Fly, Cloudflare Workers, Deno Deploy, Supabase.*
- *Migrating from raw `@modelcontextprotocol/sdk` server code, `mcp-use` v1, or `appsSdk` widgets to current `mcp-use/server`.*

Do **not** use this skill when:

- *The code imports `MCPClient`, `MCPSession`, `mcp-use/browser`, or `mcp-use/react` for app-side use — route to `build-mcp-use-client`.*
- *The work is `MCPAgent` LLM orchestration over MCP tools — route to `build-mcp-use-agent`.*
- *The user wants raw `@modelcontextprotocol/sdk` server primitives or strict stdio without `mcp-use` — route to `build-mcp-server-sdk-v1` or `build-mcp-server-sdk-v2`.*
- *The question is layer placement, import direction, composition root, or handler/use-case structure — route to `build-clean-mcp-architecture` first, then return for mechanics.*

## Coordinate with neighboring skills

| Skill | Owns | Handoff |
|---|---|---|
| `build-clean-mcp-architecture` | Folder layout, import direction, layer boundaries, composition root, config seam, handler/presenter placement. | Read first for placement; this skill second for `server.tool` and response helpers. See `references/00-clean-architecture-coordination.md`. |
| `build-mcp-use-client` | `MCPClient`, `MCPSession`, browser/react client mounting, code mode. | Hand off as soon as the target code stops importing `mcp-use/server`. |
| `build-mcp-use-agent` | `MCPAgent` orchestration where an LLM picks tools. | Hand off when the work is agent loop, not server mechanics. |
| `build-mcp-server-sdk-v1` / `build-mcp-server-sdk-v2` | Raw official SDK servers, stdio-only constraints, low-level transports. | Hand off if the user explicitly forbids `mcp-use` or needs raw SDK primitives. |
| `test-by-mcpc-cli` | Live `mcpc` session verification once a server runs. | Use after this skill produces a running server. |

Numbered folders under `references/` are local organization. Pick the intent route first; read numbered files in sequence only inside one cluster when the order matters.

## Detect intent

| Intent | Start here | Then read |
|---|---|---|
| Extend an existing `mcp-use` server | `scripts/audit-server-readiness.sh.md` | `references/04-tools/01-overview.md`, `references/05-responses/01-overview-decision-table.md`, `references/08-server-config/01-mcp-server-constructor.md`, `references/22-validate/01-mcp-inspector-walkthrough.md` |
| Greenfield HTTP tool server | `scripts/scaffold-mcp-use-server.sh.md` or `references/02-setup/05-manual-http-server.md` | `references/04-tools/01-overview.md`, `references/05-responses/01-overview-decision-table.md`, `references/22-validate/02-curl-handshake.md` |
| Strict stdio requirement | `references/02-setup/04-manual-stdio-server.md` | `references/09-transports/02-stdio.md`, then route to `build-mcp-server-sdk-v1` or `build-mcp-server-sdk-v2` |
| MCP Apps / ChatGPT widget | `references/30-workflows/11-streaming-chart-widget.md` or `references/30-workflows/12-progress-and-elicit-widget.md` | `references/18-mcp-apps/01-what-are-mcp-apps.md`, `references/18-mcp-apps/server-surface/01-widget-helper.md`, `references/18-mcp-apps/widget-react/01-mcpuseprovider.md`, `references/20-inspector/11-protocol-toggle-and-csp-mode.md` |
| Next.js drop-in | `references/30-workflows/10-add-mcp-to-existing-nextjs-app.md` | `references/19-nextjs-drop-in/01-overview.md`, `references/19-nextjs-drop-in/03-shared-aliases-and-tailwind.md`, `references/19-nextjs-drop-in/04-server-only-shimming.md`, `references/19-nextjs-drop-in/05-deploying-as-vercel-route.md` |
| Auth / OAuth | `references/11-auth/01-overview-decision-matrix.md` | `references/11-auth/02-dcr-vs-proxy-mode.md`, `references/11-auth/03-ctx-auth-object.md`, `references/11-auth/08-debugging-checklist.md`, `references/27-troubleshooting/03-oauth-and-supabase-issues.md` |
| Sessions, streaming, notifications, sampling, elicitation | `references/30-workflows/02-stateful-redis-streaming-server.md` | `references/10-sessions/01-overview.md`, `references/14-notifications/01-overview.md`, `references/13-sampling/01-overview.md`, `references/12-elicitation/01-overview.md` |
| Deploy or production hardening | `references/25-deploy/01-decision-matrix.md` | `references/25-deploy/02-pre-deploy-checklist.md`, `references/24-production/05-health-routes.md`, `references/24-production/01-graceful-shutdown.md`, relevant `references/25-deploy/platforms/*.md` |
| Troubleshoot a concrete error | `references/00-symptom-index.md` | `references/27-troubleshooting/06-decision-tree.md`, `references/27-troubleshooting/01-error-catalog.md`, then the exact cluster named by the symptom |
| Migrate from raw SDK or older `mcp-use` | `references/28-migration/01-from-modelcontextprotocol-sdk.md` or `references/28-migration/02-mcp-use-v1-to-v2.md` | `references/17-advanced/03-mcp-use-vs-official-sdk.md`, `references/09-transports/01-overview.md`, `references/28-migration/03-sse-to-streamable-http.md`, `references/28-migration/04-appssdk-to-mcpapps.md`, `references/28-migration/05-dcr-vs-proxy-mode-shift.md` |

Use `references/00-reference-index.md` only when the intent table is not specific enough or you need an exact filename.

## Core rules

- Import server APIs from `mcp-use/server`. The common exception is `Logger`, which comes from `mcp-use`.
- Declare `zod` in the project's own dependencies. Do not rely on `mcp-use` to provide it.
- Use `mcp-use` HTTP, Fetch/serverless, session, auth, and widget patterns. Do not hand-wire raw SDK transports.
- Treat strict stdio as a raw-SDK requirement, not an `mcp-use/server` branch.
- Work in the actual package, fixture, or subdirectory the user named. Do not widen to a repo-wide scan unless the target path is unknown.
- Prefer improving an existing server over replacing it.
- Never claim the server is scaffolded, installed, runnable, or verified when the environment is read-only, plan-only, or missing prerequisites you cannot add.
- For version-sensitive claims, read `references/00-version-drift.md` before editing examples, command docs, or migration guidance.

## Workflow

### 1. Lock target path and execution mode

Identify the concrete path to inspect and edit. If the user named a fixture, package, or subdirectory, use that path.

Treat the run as **plan-only** when the environment is read-only, package installation is blocked, required prerequisites are missing and cannot be added, or the user asked for analysis rather than code. Plan-only output must include exact files, install commands, implementation steps, and validation commands. It must not claim runtime validation.

### 2. Scan what already exists

Inspect the target path for:

- `package.json` with `mcp-use`, `zod`, `@mcp-use/cli`, `@mcp-use/react`
- imports from `mcp-use/server` and `mcp-use/react`
- `new MCPServer(...)`, `server.tool`, `server.resource`, `server.prompt`, `server.uiResource`
- widget signals: `resources/`, `widgetMetadata`, `useWidget`, `useCallTool`, `McpUseProvider`, `text/html;profile=mcp-app`, `text/html+skybridge`
- runtime signals: `.mcp-use/`, Docker, edge-function folders, auth config, session stores, health routes

For existing servers, run `scripts/audit-server-readiness.sh` when filesystem access is available. Its usage is documented in `scripts/audit-server-readiness.sh.md`.

Summarize target path, existing server vs no server, tools-only vs widgets, implementation-capable vs plan-only, likely server shape, and chosen entry file.

### 3. Choose the branch

**Existing server:** do not rebuild. Follow the intent row that matches the requested change, then audit nearby mechanics: tools/schemas, responses, resources/prompts, config/transports, sessions, auth, widgets, production, deploy.

**No server but enough repo context:** infer the server from REST endpoints, CLI commands, data sources, README/issue text, or a frontend that clearly needs a widget. Choose entrypoint deliberately:

- scaffolded project -> keep root `index.ts`
- manual HTTP server -> default `src/server.ts`
- empty greenfield HTTP package -> `scripts/scaffold-mcp-use-server.sh` is allowed
- existing app owns `src/index.ts` or `src/server.ts` -> add `src/mcp-server.ts`
- Next.js drop-in -> follow `references/19-nextjs-drop-in/`
- strict stdio -> route out to raw SDK skills

**Underspecified:** ask only for missing information that blocks implementation: exposed data/service/UI, transport/runtime, auth, tools/resources/prompts, widget vs tools-only, deploy target, and advanced primitives.

### 4. Preflight setup

Use `references/02-setup/01-prerequisites.md` as the setup matrix:

- Node 18+ available; Node 22 LTS preferred for current examples.
- `package.json` uses `"type": "module"`.
- `mcp-use` and `zod` are dependencies.
- `@mcp-use/cli` is present for CLI/HMR/build/start/deploy/typegen workflows unless scaffolded.
- `@mcp-use/react` is present only when building widgets.
- chosen entry file matches project shape.

Run `scripts/check-mcp-use-version.sh` when a package exists and dependency drift matters. Its usage is documented in `scripts/check-mcp-use-version.sh.md`.

If prerequisites are missing and cannot be added, switch to plan-only output.

### 5. Build or extend

Default sequence:

1. choose entry file and runtime shape (`references/02-setup/`)
2. create or refine `MCPServer` config (`references/08-server-config/`)
3. register tools with precise Zod schemas (`references/04-tools/`)
4. add resources or prompts only when they improve the interface (`references/06-resources/`, `references/07-prompts/`)
5. add auth, sessions, notifications, sampling, elicitation, widgets, or proxy only when the intent requires them
6. add health/readiness, logging, graceful shutdown, and deploy hardening when shipping beyond local dev

### 6. Validate

Pick the smallest validation set that proves the changed behavior. Do not imply a higher rung than observed.

- read-only scan: files inspected, no runtime exercised
- typecheck/build: `npm run typecheck`, `npm run build`, or project equivalent
- `mcp-use dev` / `mcp-use start`: server starts locally
- Inspector: tools/resources/prompts/widgets observed and callable
- curl handshake: initialize, tools/list, tools/call on `/mcp`
- `test-by-mcpc-cli`: named `mcpc` session connected and commands run
- deployed endpoint: health/readiness plus live MCP call against the deployed URL

For widgets, verify the text fallback and, when possible, Inspector CSP mode. For deploys, verify `references/25-deploy/02-pre-deploy-checklist.md`, `/health`, and `/ready`.

## Decision rules

- Use response helpers instead of hand-built MCP payloads.
- Default to concise complete `content`. Add `structuredContent` when there is an `outputSchema`, a typed/programmatic consumer, Code Mode, widget props, or another real parser.
- Keep `content` and `structuredContent` semantically equivalent when returning both.
- Put private, bulky, or UI-only data in `_meta`; treat ordinary `structuredContent` as potentially model-visible.
- Use `error()` for expected failures and `throw` for unexpected failures.
- Guard `ctx.elicit()` with `ctx.client.can("elicitation")`.
- Guard `ctx.sample()` with `ctx.client.can("sampling")`.
- Guard widget-only behavior with `ctx.client.supportsApps()`.
- For MCP Apps widgets, `tool.widget.name` must match `resources//widget.tsx`; always provide a text fallback.
- Wrap widget roots in `McpUseProvider`. Use `useCallTool()`, not raw `fetch()`, for MCP tool calls from widgets.
- Declare CSP domains in `widgetMetadata.metadata.csp`.
- Prefer `type: "mcpApps"` on `server.uiResource()` for dual-protocol support; `type: "appsSdk"` is deprecated.

## Guardrails

- Never import server primitives from `@modelcontextprotocol/sdk` directly.
- Never omit `zod` from the project's own dependencies.
- Never use `z.any()` or `z.unknown()` when a concrete schema is possible.
- Never leave schema fields undocumented; use `.describe()` on model-filled fields.
- Never put secrets in source, logs, widget props, widget state, or model-visible structured content.
- Never skip `allowedOrigins` and CORS decisions for public HTTP servers.
- Never access `window.openai` directly from a widget; use `useWidget` / `useCallTool`.
- Never embed an `mcp-use` server as middleware inside another framework's app. Extend the MCP server's own routes or run it side-by-side.
- Never skip `mcp-use generate-types` after schema changes if the project consumes generated widget types.

## Validate honestly

Report the exact rung reached:

| Rung | Evidence |
|---|---|
| Read-only scan | Files and references inspected; no command ran against code. |
| Static validation | Typecheck, lint, build, or generated types passed. |
| Local runtime | `mcp-use dev` or `mcp-use start` ran and exposed `/mcp`. |
| Inspector | Inspector connected; relevant surface observed or called. |
| curl handshake | `initialize`, `tools/list`, and at least one relevant `tools/call` succeeded. |
| `mcpc` live test | `test-by-mcpc-cli` session name and commands are reported. |
| Deployed endpoint | health/readiness and live MCP operation verified against public URL. |

If using `test-by-mcpc-cli`, name the session and list the exact commands. For plan-only runs, mark runtime validation blocked and provide exact commands to run later.

## Output contract

Unless the user asks for another format, report:

1. target path and scan summary
2. chosen branch and entrypoint decision
3. implementation or exact plan
4. validation rung reached, commands run, and blockers
5. if widgets changed: text fallback and CSP-mode verification state
6. if deploy/production changed: health/readiness and pre-deploy checklist state
7. key references used, with exact paths for the route actually followed

## Reference routing

Start with intent or symptoms; use inventory only as fallback.

- **Symptom index:** `references/00-symptom-index.md`
- **Clean architecture handoff:** `references/00-clean-architecture-coordination.md`
- **Version drift policy:** `references/00-version-drift.md`
- **Full inventory:** `references/00-reference-index.md`
- **Bundled scripts:** `scripts/check-mcp-use-version.sh.md`, `scripts/audit-server-readiness.sh.md`, `scripts/scaffold-mcp-use-server.sh.md`
- **Foundations:** `references/01-concepts/01-what-is-mcp-use.md`, `references/01-concepts/02-server-vs-client-vs-agent.md`, `references/01-concepts/03-transports-overview.md`, `references/01-concepts/04-stateful-vs-stateless.md`, `references/01-concepts/05-mcp-spec-version-history.md`, `references/01-concepts/06-mcp-apps-vs-widgets-terminology.md`, `references/01-concepts/07-this-skill-vs-build-mcp-use-client.md`
- **Setup:** `references/02-setup/01-prerequisites.md`, `references/02-setup/02-scaffold-with-create-mcp-use-app.md`, `references/02-setup/03-template-flags.md

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yigitkonur](https://github.com/yigitkonur)
- **Source:** [yigitkonur/skills-by-yigitkonur](https://github.com/yigitkonur/skills-by-yigitkonur)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yigitkonur-skills-by-yigitkonur-build-mcp-use-server
- Seller: https://agentstack.voostack.com/s/yigitkonur
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.