building-mcp-servers · git:20260519.40bb110 · 2026-05-19 · sha256 442e557c964eeabf
building-mcp-servers git:20260519.40bb110A
Immutable. This exact content never changes and is served at /api/v1/blob/442e557c964eeabf.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_ciortu6rllljyzsn/442e557c964eeabffaa9b29ad2c917f12059375ea76936e7cdf7d1eb731acd0b.json
Then /plugin install building-mcp-servers@markdownregistry-ciortu6rllljyzsn in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: building-mcp-servers
description: Authors an MCP server with the official SDK and gates.
tier: optional
category: integration
created_by: human
platforms: [windows, macos, linux]
tags: [mcp, sdk, server-authoring]
author: Andreas Wasita (@andreaswasita)
---
# Building MCP Servers Skill
Authors a Model Context Protocol server in TypeScript or Python using the official SDKs (`@modelcontextprotocol/sdk`, `mcp`), with deliberate tool/resource/prompt design, both stdio and Streamable HTTP transports, OAuth 2.1 auth, and a test fixture. Does NOT roll its own JSON-RPC framing and does NOT ship without registry + config snippet.
## When to Use
- A required system is not in `mcp/registry.yaml`.
- An existing MCP server is too broad; you need a domain-specific facade.
- User says "build", "write", "author", "create" + "MCP server".
- Wrapping internal APIs so an agent can call them without bespoke skills.
## Prerequisites
- Node 20+ (TypeScript) or Python 3.11+.
- The official SDK installed (`@modelcontextprotocol/sdk` or `mcp`).
- An auth strategy decided upfront (CLI inheritance for local, OAuth 2.1 + PKCE for hosted).
- `mcp/registry.yaml` and `mcp/configs/` writable.
- `@modelcontextprotocol/inspector` for handshake debugging.
## How to Run
```text
1. Pick primitives: tools / resources / prompts. Default to tools.
2. Design tool names (verb_object) and JSON Schema inputs.
3. Scaffold the server with the official SDK + stdio transport.
4. Add Streamable HTTP transport if the server is hosted.
5. Implement auth — CLI inheritance (local) or OAuth 2.1 + PKCE (hosted).
6. Add tests: in-memory transport unit tests + a real stdio smoke test.
7. Register in `mcp/registry.yaml` and add a `mcp/configs/` snippet.
```
## Quick Reference
| Primitive | Use for | Mental model |
|---|---|---|
| tools | Side-effectful or arg'd queries | RPC the agent decides to invoke |
| resources | Read-only documents addressable by URI | Things the agent or user attaches |
| prompts | Pre-baked agent instructions | Slash commands the user invokes |
| Concern | Rule |
|---|---|
| Tool naming | `verb_object` snake_case (`get_my_deals`) |
| Input schema | JSON Schema, required fields marked, `description` on every property |
| Output | Text content first; structured JSON in a second content block |
| Logging | stderr only — stdout is reserved for JSON-RPC framing |
| Auth | CLI inheritance (local) or OAuth 2.1 + PKCE (hosted), never tokens in tool args |
| Pagination | Every list tool has `limit` (default ≤50) and `cursor` |
| Idempotency | Mutations accept a client-provided idempotency key |
| Versioning | Bump `serverInfo.version` on schema changes |
## Procedure
### Step 1: Choose Primitives
Default to tools. Use resources only when the data is naturally addressable by URI. Use prompts only when the user invokes them explicitly (slash commands).
### Step 2: Design Tool Surface
For each tool:
- Name: `verb_object` snake_case.
- Description: answer "when do I call this?", not "what does it do internally". Lead with the trigger context.
- Input: JSON Schema with `required`, every property has a human-readable `description`.
- Output: text summary first; machine-readable JSON in a second content block if the agent will chain calls.
### Step 3: Stdio Scaffold (TypeScript)
```ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server(
{ name: "my-server", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler(/* tools/list */, async () => ({ tools: [...] }));
server.setRequestHandler(/* tools/call */, async (req) => { /* ... */ });
await server.connect(new StdioServerTransport());
```
### Step 4: Streamable HTTP (Hosted)
- Use `StreamableHTTPServerTransport`.
- Mount behind a real auth provider (Entra ID, Auth0, custom OAuth 2.1).
- Implement `/mcp` POST + GET (SSE streaming). Do not invent endpoints.
- Add protected resource metadata so clients can discover the auth server.
### Step 5: Stdout Discipline
The single most common failure: a `console.log` or stray print before the JSON-RPC handshake corrupts the stream. The client silently dies.
- TypeScript: route logs to `console.error`.
- Python: configure `logging` to `sys.stderr`, never `print`.
### Step 6: Auth Without Inline Secrets
- Local dev: inherit from `az`, `gh`, `kubectl`, `gcloud`.
- Hosted: OAuth 2.1 + PKCE. Map `Authorization: Bearer …` to your resource server.
- Never accept tokens via tool arguments — that places them in the agent's context window and chat history.
### Step 7: Tests
- Unit-test handlers with the SDK's in-memory transport.
- Smoke test: spawn the server, call `tools/list` then one representative `tools/call`.
- Ship an `auth_status` tool for diagnostics.
- Provide a `--inspect` mode wired to `@modelcontextprotocol/inspector`.
### Step 8: Register and Document
After the server works:
1. Add an entry to `mcp/registry.yaml` (transport, scopes, auth model).
2. Add a config snippet under `mcp/configs/`.
3. Cross-link from the relevant consumer skill.
## Pitfalls
- **DO NOT** log to stdout in a stdio server.
- **DO NOT** build a mega-tool with a `mode` enum that switches behavior. One job per tool.
- **DO NOT** write tool descriptions that explain implementation. Lead with the trigger context.
- **DO NOT** return unbounded result sets. Every list tool has `limit` and `cursor`.
- **DO NOT** accept credentials as tool arguments. They will end up in chat history.
- **DO NOT** re-implement JSON-RPC framing. Use the SDK.
- **DO NOT** ship a server without an `auth_status` / health tool.
## Verification
- [ ] Built with `@modelcontextprotocol/sdk` (TS) or `mcp` (Python) — no custom framing.
- [ ] All tools have JSON Schema input with `required` set and per-property `description`.
- [ ] Stdout is reserved for JSON-RPC; all logs go to stderr.
- [ ] Auth uses CLI inheritance (local) or OAuth 2.1 + PKCE (hosted).
- [ ] `auth_status` tool exists.
- [ ] Smoke test covers `tools/list` and one `tools/call` over real stdio.
- [ ] Registry entry and `mcp/configs/` snippet exist.
- [ ] `serverInfo.version` set and bumped on every schema change.