| name | develop-mcp-server-ts |
| description | Standardized workflow for building MCP servers in TypeScript. Use when building or extending an MCP server with the official TypeScript SDK (tools, resources, prompts), adding tool annotations (title, readOnlyHint, etc.), choosing Stdio vs Streamable HTTP transport, or testing with MCP Inspector or Claude Desktop. |
Develop MCP Server (TypeScript)
Purpose
Provide a repeatable, documented workflow for building MCP servers with the official TypeScript SDK so that agents and developers can add tools, resources, and prompts without ad-hoc discovery. Follow this workflow to go from requirements to a testable server (Stdio or Streamable HTTP). The skill follows MCP specification 2025-11-25 for tools, resources, prompts, and server utilities (logging, completion, pagination).
Workflow Checklist
Detailed Instructions
1. Requirements discovery
Read the MCP specification summary for:
- Primitives: Tools (callable by the LLM), Resources (read-only context), Prompts (reusable templates).
- Transports: Stdio (local, one client per process) vs Streamable HTTP (remote, many clients).
- Lifecycle: Initialize, negotiate capabilities, then list/call tools or read resources.
Decide which primitives your server needs and whether it will run locally (Stdio) or be hosted (Streamable HTTP).
2. Project initialization
- Create a package (e.g.
pnpm init or npm init -y).
- Install the v2 split packages (not the legacy monolith
@modelcontextprotocol/sdk):
- Server core:
pnpm add @modelcontextprotocol/server@2.0.0 zod (Zod 4 / Standard Schema required for tool inputSchema).
- Node HTTP transport (when needed):
pnpm add @modelcontextprotocol/node@2.0.0.
- Optional for tests:
pnpm add -D @modelcontextprotocol/client.
- Set
"type": "module" in package.json if using ESM.
- Use a tsconfig with
"module": "Node16", "moduleResolution": "Node16", "target": "ES2022", and "outDir": "./build" (or similar).
3. Implementation patterns
Use the TypeScript SDK cheatsheet for:
- Creating an
McpServer and connecting a transport. For Stdio (recommended local path in this repo), use the legacy-era pattern server.connect(new StdioServerTransport()). serveStdio is a modern/dual-era opt-in helper — not the default here yet.
- For Streamable HTTP on Node, use
NodeStreamableHTTPServerTransport from @modelcontextprotocol/node.
- Registering tools with
server.registerTool(name, { description, inputSchema }, handler). Use Zod (Zod 4 / Standard Schema) for inputSchema (e.g. { id: z.string() }). Return { content: [{ type: "text", text: "..." }] }. Add tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) when they help clients present or approve tools. For reversible destructive operations (e.g. delete group), set destructiveHint: true. Do not expose irrecoverable deletes on MCP (ADR-0004).
- Registering resources if needed (URI templates and read handler).
- Logging: For Stdio transport, never write to stdout; use
console.error or a logger that writes to stderr.
4. Testing
- MCP Inspector: Run
npx @modelcontextprotocol/inspector, then start your server (e.g. with the command you would use in Claude Desktop). Use the Inspector UI to list tools and call them.
- Claude Desktop: Edit the config file (see Connect to local MCP servers). Add an entry under
mcpServers with command and args (e.g. node and ["/path/to/build/index.js"]). Restart Claude Desktop fully (quit the app, then reopen). Verify the server appears under Connectors.
Success Criteria
- The server lists and executes tools (and optionally resources/prompts) correctly.
- For Stdio: No use of
console.log; logs go to stderr.
- Tool inputSchema uses Zod (Zod 4 / Standard Schema) and matches the SDK expectations.
- Tool names follow spec 2025-11-25 (1–128 chars, allowed characters); errors use tool execution result (
isError: true) or protocol errors as appropriate.
- Tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are used where they help clients present or approve tools.
- Official links (TypeScript SDK, MCP spec 2025-11-25) are used for version and API details.
References
