MCP Server Builder
An MCP server is an API whose caller is a language model. It picks tools by name and description, pays in context for every byte returned, and cannot read your docs. The costly mistake this skill prevents is wrapping a REST API one endpoint per tool. That produces forty thin tools, vague descriptions, unbounded JSON and errors thrown as protocol failures, and the result is a server the model misuses, that floods the context window, and that fails silently.
Operating procedure
Step 1: Write the task list before the tool list
List the 5-10 concrete things users will ask for, such as "find open bugs assigned to me". Each task should take one or two calls. One search_issues with filters beats three list-and-filter tools; chain upstream calls inside the server.
Step 2: Choose the transport and protocol posture
- stdio is for a local subprocess (filesystem, git, CLIs). On stdio, stdout belongs to the protocol: log to stderr, never
console.log or print.
- Streamable HTTP is for remote or shared servers. Since spec revision 2026-07-28 the protocol is stateless:
- There are no sessions, no
Mcp-Session-Id and no initialize handshake. Each request carries its protocol version and client capabilities in _meta.
- Servers MUST implement
server/discover to advertise their versions, capabilities and identity. Change notifications go over subscriptions/listen.
- Put cross-call state in server-minted handles that are passed back as ordinary tool arguments, not in connection state.
- Many deployed clients still speak 2025-era revisions, which use
initialize and sessions, so serve both eras. Use an SDK entry point that negotiates the era rather than hand-rolling the wire format.
- The old HTTP+SSE transport is deprecated, so do not build on it.
Step 3: Pick the right primitive
- Tools are actions or queries the model invokes on its own.
- Resources are addressable, read-only context that the app or user attaches.
- Prompts are templates the user picks, often shown as slash commands.
Do not adopt the deprecated Roots, Sampling or Logging features in new servers. Instead, take paths as tool parameters, call your LLM provider directly, and log to stderr or OpenTelemetry. If a call needs more input from the user mid-flight, use the multi round-trip pattern. The server returns an input-required result (resultType: "input_required") and the client retries the request with the answers. The server never sends its own requests to the client.
Step 4: Design each tool's contract
- Name it
verb_noun in snake_case, unambiguous across servers (search_issues, not search).
- Description: the first sentence says what the tool returns and when to use it. Then constraints, next calls, and when not to use it.
- Input schema: JSON Schema with types, enums for closed sets, defaults, and a description on every property. Accept human identifiers like
PROJ-123, not internal IDs the model cannot know.
- Annotations: set
readOnlyHint, destructiveHint, idempotentHint and openWorldHint honestly, plus a title. They drive the client's confirmation UX but are not a security boundary.
- Output: concise text the model can reason over. Add
outputSchema and structuredContent when machine consumers need them.
- Order: return the tool list in a deterministic order so client and prompt caches hit.
Step 5: Bound every response
- Cap lists at a default of 20 and a hard max of 100, and return an opaque cursor for the next page.
- Truncate long fields and say so, for example: "truncated; call get_issue for the full text".
- Budget in UTF-8 bytes, not items or JS string length, because one item can be 500 KB. Cut on a character boundary.
Step 6: Handle errors in the right layer
- Tool execution errors return a result with
isError: true and an actionable message: what failed and what to try next. This covers an upstream 404, a rate limit, or bad arguments the model can fix. The TypeScript SDK v2 already returns schema-validation failures this way.
- Protocol errors are JSON-RPC errors such as unknown method, malformed request or
UnsupportedProtocolVersionError. The model often never sees them.
Step 7: Secure remote servers
- Act as an OAuth 2.1 resource server. Unauthenticated requests get
401 with WWW-Authenticate: Bearer resource_metadata="https://host/.well-known/oauth-protected-resource".
- Serve protected resource metadata (RFC 9728) that names your authorization server. PKCE is mandatory. Clients should register with Client ID Metadata Documents; Dynamic Client Registration is deprecated and kept only for compatibility.
- Check that every token's audience is your server. Never pass the client's token through to upstream APIs.
- Validate the
Origin header on every Streamable HTTP server. Bind local servers to 127.0.0.1.
Step 8: Test, then version
- Run the MCP Inspector (
npx @modelcontextprotocol/inspector <server command>) on every tool: valid, invalid, empty, last page, upstream outage. Test a current and a 2025-era client.
- Try real prompts: if the model picks the wrong tool, fix the description.
- Tool names and schemas are a public API: add optional fields freely, never repurpose a name or change semantics.
Worked example - TypeScript SDK v2, stdio
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
const MAX_BYTES = 24_000;
// Cut at a code-point boundary once the UTF-8 byte budget is spent.
function clip(text: string): string {
let bytes = 0, end = 0;
for (const ch of text) {
bytes += Buffer.byteLength(ch);
if (bytes > MAX_BYTES) return text.slice(0, end) + "\n[truncated - narrow the query]";
end += ch.length;
}
return text;
}
function buildServer() {
const server = new McpServer({ name: "issues", version: "1.2.0" });
server.registerTool(
"search_issues",
{
title: "Search issues",
description:
"Returns up to `limit` issues (key, title, status, assignee) matching a query; use it to find issues before reading or updating one. Paged via `cursor`; use get_issue for full text.",
inputSchema: z.object({
query: z.string().min(1).describe("Free-text search over title and body"),
status: z.enum(["open", "closed", "any"]).default("open"),
limit: z.number().int().min(1).max(100).default(20),
cursor: z.string().optional().describe("Opaque cursor from a previous call"),
}),
annotations: { readOnlyHint: true, openWorldHint: true },
},
async ({ query, status, limit, cursor }) => {
try {
const page = await tracker.search({ query, status, limit, cursor }); // your API client
let text = page.items
.map((i) => `${i.key} [${i.status}] ${i.title} (${i.assignee ?? "unassigned"})`)
.join("\n") || "No matches. Try a broader query or status=any.";
text = clip(text);
if (page.nextCursor) text += `\nMore: cursor=${page.nextCursor}`;
return { content: [{ type: "text", text }] };
} catch (err) {
return { isError: true, content: [{ type: "text", text: `Search failed: ${safeMessage(err)}. Retry shortly if rate-limited.` }] };
}
}
);
return server;
}
serveStdio(buildServer); // serves current and 2025-era clients by default
For HTTP, pass the same factory to createMcpHandler. The maintenance-only v1.x SDK (@modelcontextprotocol/sdk) speaks only the 2025 era. For Python (FastMCP), check which revisions your version supports.
Thresholds
- Aim for 5-15 tools per server. Above about 20, tool-selection accuracy tends to drop.
- Description first sentence: under ~200 characters, self-sufficient.
- Page size: default 20, max 100. Budget about 25 KB of text per response.
- Return within ~30 s; longer work needs progress notifications or start/poll tools.
- Every tool has annotations, and every destructive tool sets
destructiveHint: true.
Deliverable
A task-to-tool map, transport and era posture with reasons, tool definitions, bounded paginated outputs, an error contract, remote auth setup, Inspector results for both eras, and a README of tools and env vars.
Do NOT
- Do not mirror REST endpoints one to one.
- Do not keep per-connection state on the current protocol revision.
- Do not throw for recoverable failures or return unbounded payloads.
- Do not treat annotations as authorization or pass client tokens upstream.
- Do not drop 2025-era clients without a deliberate decision.
- Do not guess SDK method names; check the installed version's types.
Quality bar
- An unprompted model picks the right tool for every task on the list.
- Responses fit the byte budget, truncation is announced, and every failure message is actionable.
- Both protocol eras pass the Inspector checklist.
- The remote server returns a spec-correct 401 challenge and rejects tokens for the wrong audience or Origin.
1---2name: mcp-builder3description: Design and build Model Context Protocol servers that models use correctly - choosing stdio vs stateless Streamable HTTP while still serving 2025-era clients, shaping a few task-level tools with clear descriptions, JSON Schema inputs and honest annotations, bounding and paginating output, returning recoverable errors as isError results, securing remote servers with OAuth 2.1, and testing with the MCP Inspector. Use when someone asks "build an MCP server for our API", "turn this service into MCP tools", "why does the model keep calling the wrong tool", "add OAuth to my remote MCP server", or "my stdio server keeps disconnecting". Do NOT use for designing a REST or GraphQL API consumed by human-written code - use api-design instead - or for coordinating multiple LLM agents - use agent-orchestration instead.4metadata:5 source: https://skillmd.com/skills/skillmedev/mcp-builder6 title: "MCP Server Builder"7---89# MCP Server Builder1011An MCP server is an API whose caller is a language model. It picks tools by name and description, pays in context for every byte returned, and cannot read your docs. The costly mistake this skill prevents is wrapping a REST API one endpoint per tool. That produces forty thin tools, vague descriptions, unbounded JSON and errors thrown as protocol failures, and the result is a server the model misuses, that floods the context window, and that fails silently.1213## Operating procedure1415### Step 1: Write the task list before the tool list1617List the 5-10 concrete things users will ask for, such as "find open bugs assigned to me". Each task should take one or two calls. One `search_issues` with filters beats three list-and-filter tools; chain upstream calls inside the server.1819### Step 2: Choose the transport and protocol posture2021- **stdio** is for a local subprocess (filesystem, git, CLIs). On stdio, stdout belongs to the protocol: log to stderr, never `console.log` or `print`.22- **Streamable HTTP** is for remote or shared servers. Since spec revision 2026-07-28 the protocol is stateless:23 - There are no sessions, no `Mcp-Session-Id` and no `initialize` handshake. Each request carries its protocol version and client capabilities in `_meta`.24 - Servers MUST implement `server/discover` to advertise their versions, capabilities and identity. Change notifications go over `subscriptions/listen`.25 - Put cross-call state in server-minted handles that are passed back as ordinary tool arguments, not in connection state.26- Many deployed clients still speak 2025-era revisions, which use `initialize` and sessions, so serve both eras. Use an SDK entry point that negotiates the era rather than hand-rolling the wire format.27- The old HTTP+SSE transport is deprecated, so do not build on it.2829### Step 3: Pick the right primitive3031- **Tools** are actions or queries the model invokes on its own.32- **Resources** are addressable, read-only context that the app or user attaches.33- **Prompts** are templates the user picks, often shown as slash commands.3435Do not adopt the deprecated Roots, Sampling or Logging features in new servers. Instead, take paths as tool parameters, call your LLM provider directly, and log to stderr or OpenTelemetry. If a call needs more input from the user mid-flight, use the multi round-trip pattern. The server returns an input-required result (`resultType: "input_required"`) and the client retries the request with the answers. The server never sends its own requests to the client.3637### Step 4: Design each tool's contract3839- **Name** it `verb_noun` in snake_case, unambiguous across servers (`search_issues`, not `search`).40- **Description**: the first sentence says what the tool returns and when to use it. Then constraints, next calls, and when not to use it.41- **Input schema**: JSON Schema with types, enums for closed sets, defaults, and a description on every property. Accept human identifiers like `PROJ-123`, not internal IDs the model cannot know.42- **Annotations**: set `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint` honestly, plus a `title`. They drive the client's confirmation UX but are not a security boundary.43- **Output**: concise text the model can reason over. Add `outputSchema` and `structuredContent` when machine consumers need them.44- **Order**: return the tool list in a deterministic order so client and prompt caches hit.4546### Step 5: Bound every response4748- Cap lists at a default of 20 and a hard max of 100, and return an opaque cursor for the next page.49- Truncate long fields and say so, for example: "truncated; call get_issue for the full text".50- Budget in UTF-8 bytes, not items or JS string length, because one item can be 500 KB. Cut on a character boundary.5152### Step 6: Handle errors in the right layer5354- **Tool execution errors** return a result with `isError: true` and an actionable message: what failed and what to try next. This covers an upstream 404, a rate limit, or bad arguments the model can fix. The TypeScript SDK v2 already returns schema-validation failures this way.55- **Protocol errors** are JSON-RPC errors such as unknown method, malformed request or `UnsupportedProtocolVersionError`. The model often never sees them.5657### Step 7: Secure remote servers5859- Act as an OAuth 2.1 resource server. Unauthenticated requests get `401` with `WWW-Authenticate: Bearer resource_metadata="https://host/.well-known/oauth-protected-resource"`.60- Serve protected resource metadata (RFC 9728) that names your authorization server. PKCE is mandatory. Clients should register with Client ID Metadata Documents; Dynamic Client Registration is deprecated and kept only for compatibility.61- Check that every token's audience is your server. Never pass the client's token through to upstream APIs.62- Validate the `Origin` header on every Streamable HTTP server. Bind local servers to `127.0.0.1`.6364### Step 8: Test, then version6566- Run the MCP Inspector (`npx @modelcontextprotocol/inspector <server command>`) on every tool: valid, invalid, empty, last page, upstream outage. Test a current and a 2025-era client.67- Try real prompts: if the model picks the wrong tool, fix the description.68- Tool names and schemas are a public API: add optional fields freely, never repurpose a name or change semantics.6970## Worked example - TypeScript SDK v2, stdio7172```typescript73import { McpServer } from "@modelcontextprotocol/server";74import { serveStdio } from "@modelcontextprotocol/server/stdio";75import * as z from "zod/v4";7677const MAX_BYTES = 24_000;7879// Cut at a code-point boundary once the UTF-8 byte budget is spent.80function clip(text: string): string {81 let bytes = 0, end = 0;82 for (const ch of text) {83 bytes += Buffer.byteLength(ch);84 if (bytes > MAX_BYTES) return text.slice(0, end) + "\n[truncated - narrow the query]";85 end += ch.length;86 }87 return text;88}8990function buildServer() {91 const server = new McpServer({ name: "issues", version: "1.2.0" });92 server.registerTool(93 "search_issues",94 {95 title: "Search issues",96 description:97 "Returns up to `limit` issues (key, title, status, assignee) matching a query; use it to find issues before reading or updating one. Paged via `cursor`; use get_issue for full text.",98 inputSchema: z.object({99 query: z.string().min(1).describe("Free-text search over title and body"),100 status: z.enum(["open", "closed", "any"]).default("open"),101 limit: z.number().int().min(1).max(100).default(20),102 cursor: z.string().optional().describe("Opaque cursor from a previous call"),103 }),104 annotations: { readOnlyHint: true, openWorldHint: true },105 },106 async ({ query, status, limit, cursor }) => {107 try {108 const page = await tracker.search({ query, status, limit, cursor }); // your API client109 let text = page.items110 .map((i) => `${i.key} [${i.status}] ${i.title} (${i.assignee ?? "unassigned"})`)111 .join("\n") || "No matches. Try a broader query or status=any.";112 text = clip(text);113 if (page.nextCursor) text += `\nMore: cursor=${page.nextCursor}`;114 return { content: [{ type: "text", text }] };115 } catch (err) {116 return { isError: true, content: [{ type: "text", text: `Search failed: ${safeMessage(err)}. Retry shortly if rate-limited.` }] };117 }118 }119 );120 return server;121}122123serveStdio(buildServer); // serves current and 2025-era clients by default124```125126For HTTP, pass the same factory to `createMcpHandler`. The maintenance-only v1.x SDK (`@modelcontextprotocol/sdk`) speaks only the 2025 era. For Python (FastMCP), check which revisions your version supports.127128## Thresholds129130- Aim for 5-15 tools per server. Above about 20, tool-selection accuracy tends to drop.131- Description first sentence: under ~200 characters, self-sufficient.132- Page size: default 20, max 100. Budget about 25 KB of text per response.133- Return within ~30 s; longer work needs progress notifications or start/poll tools.134- Every tool has annotations, and every destructive tool sets `destructiveHint: true`.135136## Deliverable137138A task-to-tool map, transport and era posture with reasons, tool definitions, bounded paginated outputs, an error contract, remote auth setup, Inspector results for both eras, and a README of tools and env vars.139140## Do NOT141142- Do not mirror REST endpoints one to one.143- Do not keep per-connection state on the current protocol revision.144- Do not throw for recoverable failures or return unbounded payloads.145- Do not treat annotations as authorization or pass client tokens upstream.146- Do not drop 2025-era clients without a deliberate decision.147- Do not guess SDK method names; check the installed version's types.148149## Quality bar150151- An unprompted model picks the right tool for every task on the list.152- Responses fit the byte budget, truncation is announced, and every failure message is actionable.153- Both protocol eras pass the Inspector checklist.154- The remote server returns a spec-correct 401 challenge and rejects tokens for the wrong audience or Origin.