mcp-server
/mcp-server
Build, extend, and maintain a Model Context Protocol (MCP) server across its whole lifecycle against the current spec and official SDKs. Covers the architecture, choosing a transport (stdio vs Streamable HTTP), writing tool definitions agents actually use, adding tools without breaking existing agents, versioning and deprecation, the security threat model (tool poisoning, token passthrough, prompt injection, OAuth), testing with the MCP Inspector, and publishing to the registry. Use when building an MCP server, exposing a CLI, API, or app to AI agents (Claude Code, Cursor, Cline, Windsurf), ad
- Author
- saschb2b ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 13
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Build, extend, and maintain a Model Context Protocol (MCP) server across its whole lifecycle against the current spec and official SDKs. Covers the architecture, choosing a transport (stdio vs Streamable HTTP), writing tool definitions agents actually use, adding tools without breaking existing agents, versioning and deprecation, the security threat model (tool poisoning, token passthrough, prompt injection, OAuth), testing with the MCP Inspector, and publishing to the registry. Use when building an MCP server, exposing a CLI, API, or app to AI agents (Claude Code, Cursor, Cline, Windsurf), ad
Original author description
Build, extend, and maintain a Model Context Protocol (MCP) server across its whole lifecycle against the current spec and official SDKs. Covers the architecture, choosing a transport (stdio vs Streamable HTTP), writing tool definitions agents actually use, adding tools without breaking existing agents, versioning and deprecation, the security threat model (tool poisoning, token passthrough, prompt injection, OAuth), testing with the MCP Inspector, and publishing to the registry. Use when building an MCP server, exposing a CLI, API, or app to AI agents (Claude Code, Cursor, Cline, Windsurf), ad
How it works
- Target the current protocol
- Step 1: Pick the transport
- Step 2: The five layers
- Step 3: Identify the bridge — this decides everything else
- Step 4: Write ONE tool end to end before anything else
- Writing tools agents actually use
- Extending without breaking agents
- Security non-negotiables
- Test, debug, publish
- Reference bundle
SKILL.md preview
---
name: mcp-server
description: Build, extend, and maintain a Model Context Protocol (MCP) server across its whole lifecycle against the current spec and official SDKs. Covers the architecture, choosing a transport (stdio vs Streamable HTTP), writing tool definitions agents actually use, adding tools without breaking existing agents, versioning and deprecation, the security threat model (tool poisoning, token passthrough, prompt injection, OAuth), testing with the MCP Inspector, and publishing to the registry. Use when building an MCP server, exposing a CLI, API, or app to AI agents (Claude Code, Cursor, Cline, Windsurf), adding or reviewing MCP tools, fixing an agent that calls the wrong tool or loads too many, securing or authorizing an MCP server, migrating transports, or shipping and versioning one. Also for any new agent-tool integration where the target has a scripting API, CLI, or HTTP surface.
tags: [ai-agents, mcp, backend]
date: 2026-06-21
source_post: how-to-build-mcp-server
---
# Build and maintain an MCP server
Scaffolding an MCP server is the easy 10%. The heavy lifting is everything after `init`: writing tool definitions the agent reads correctly, extending the surface without breaking agents that already depend on it, defending against tool poisoning and prompt injection, and operating the thing once it is remote. This skill covers the whole lifecycle. The deep reference for each phase is the vendored OKF bundle in [references/](./references/index.md); SKILL.md is the procedure.
## Target the current protocol
MCP uses date-string protocol revisions. As of 2026-06-21 the current stable revision is **2025-11-25** (it superseded `2025-06-18`); a stateless-core revision `2026-07-28` is the imminent next release. Build against `2025-11-25` and let the SDK negotiate older clients. The production SDK is **`@modelcontextprotocol/sdk`** (v1.x, TypeScript). The split `@modelcontextprotocol/server` + `/client` packages are the unreleased V2 line, not current. Full protocol surface, lifecycle, and result shapes in [protocol.md](./references/protocol.md).
## Step 1: Pick the transport
| Use | Transport | Why |
|---|---|---|
| Local, client spawns the server as a subprocess, one user | **stdio** | No auth, no sessions, no scaling. Default for local tools. Log to **stderr only**. |
| Remote, hosted, multiple clients | **Streamable HTTP** | Single endpoint (POST + optional SSE upgrade), `Mcp-Session-Id`, OAuth, you own scaling and ops. |
Prefer stdio until you genuinely need remote multi-client access. The old HTTP+SSE transport is deprecated (replaced by Streamable HTTP in `2025-03-26`). Transport mechanics, the stdio-vs-HTTP operational cliff, and sessions are in [protocol.md](./references/protocol.md) and [maintenance.md](./references/maintenance.md).
## Step 2: The five layers
Every server, regardless of target, has the same skeleton:
1. **Server & transport** (`src/index.ts`) — entry point, lifecycle, cleanup, chosen transport.
2. **Tool definitions** (`src/tool-definitions.ts`) — the contract the agent reads to decide what to call. **The single most important file.**
3. **Router & handlers** (`src/tool-router.ts`, `src/handlers/*.ts`) — dispatch, validation, response shaping.
4. **The bridge** (`src/executor.ts`, `scripts/*`) — how you actually talk to the target. **80% of the work.**
5. **Security & validation** (`src/utils.ts`) — input validation, `execFile` over `exec`, path checks, tool filtering.
Single production dependency: `@modelcontextprotocol/sdk` (plus `zod` for schemas). TypeScript, ESLint, and the test runner are dev-only.
## Step 3: Identify the bridge — this decides everything else
Ask how the target lets you automate it:
| Target offers | Bridge pattern | Example |
|---|---|---|
| Scripting API (Lua, GDScript, Python) | Subprocess + script-injection dispatcher in the target's language | Aseprite (Lua), Godot (GDScript) |
| REST / HTTP API | `fetch` calls from handlers | Any web service |
| Rich CLI | `execFile` directly | FFmpeg, ImageMagick |
| Socket / TCP / WebSocket server | Persistent connection, state in a shared context | Godot interactive mode |
| Native SDK | Direct import if Node-compatible | SQLite, native modules |
If two patterns apply, prefer the lower-state one (subprocess over persistent socket). State means lifecycle management.
## Step 4: Write ONE tool end to end before anything else
Do not define 50 tools up front. Pick the simplest useful operation (`get_version`, `create_file`), wire it through all five layers with the SDK's `registerTool(name, { description, inputSchema, annotations }, handler)`, then watch an agent call it in the Inspector:
```
npx @modelcontextprotocol/inspector node build/index.js
```
If the tool list reads as confusing to you, it reads as confusing to the agent. Once one tool works, adding more is mechanical.
## Writing tools agents actually use
The description is the only documentation the agent has, and tool definitions cost tokens on every request before the user speaks. Anthropic's guidance ([tool-design.md](./references/tool-design.md)) in four rules:
1. **Build few high-impact workflow tools, do not wrap every API endpoint.** Consolidate `list_users` + `list_events` + `create_event` into one `schedule_event`. More tools confuse the agent and burn its context.
2. **Write the description like onboarding a new hire.** Precise verbs, precise parameter names (`user_id` not `user`), enums over free strings, required vs optional marked and defaults documented.
3. **Return high-signal context.** Natural-language names over opaque UUIDs; paginate, filter, and truncate large results; offer a `response_format` enum (`concise`/`detailed`) instead of always dumping everything.
4. **Set annotations truthfully** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` — and surface tool failures as `isError: true` with an actionable message so the model self-corrects.
## Extending without breaking agents
Adding a tool touches four places: the definition, the handler, the `HANDLER_MAP` entry, and the bridge operation (if Layer 4 uses one). Document this in `CONTRIBUTING.md` so contributors don't drift.
Evolving an existing tool is where servers break their consumers. **Additive is safe** (new tools, new *optional* params, adding `outputSchema`). **Breaking is not** (removing or renaming a tool, adding a required param, narrowing a type, or silently changing semantics). MCP has no formal tool-deprecation flag, so the sanctioned path is **name-versioning**: ship `export_v2`, keep `export` working, mark `export` deprecated in its description. Fire `notifications/tools/list_changed` when the set changes. The full versioning, deprecation, `_meta`, toolsets, pagination, and observability playbook is in [maintenance.md](./references/maintenance.md).
## Security non-negotiables
MCP servers run with real privileges and read agent-influenced, attacker-reachable input. The minimum bar (full threat model and OAuth in [security.md](./references/security.md)):
- **`execFile`/`spawn`, never `exec`.** Args as an array, no shell string interpolation. Allowlist binaries.
- **Validate every path and input.** Resolve to absolute and verify it stays under the intended base; reject `..` before passing to the bridge.
- **Secrets via env vars, never CLI args** (args leak through `ps` / `/proc`). stdio servers read credentials from the environment.
- **Remote servers: OAuth 2.1.** Validate the token audience (RFC 8707) — **token passthrough is forbidden**. Validate the `Origin` header (DNS rebinding) and bind local HTTP to `127.0.0.1`.
- **Treat tool descriptions AND tool results as untrusted.** Tool poisoning, line jumping, and rug pulls all hide instructions where the agent reads them; keep destructive actions behind human approval.
## Test, debug, publish
- **Test** with the MCP Inspector (`npx @modelcontextprotocol/inspector ...`), unit-test handlers, and run an eval-driven loop on tool quality. stdio servers must log to **stderr** — a stray `stdout` write corrupts the JSON-RPC stream. See [testing.md](./references/testing.md).
- **Publish** via `server.json` (reverse-DNS name, immutable version) to the registry, and give consumers the `mcpServers` config block; MCPB (formerly DXT) packs a one-click local install. See [publishing.md](./references/publishing.md).
## Reference bundle
The post-init knowledge lives in [references/](./references/index.md) as a conformant OKF bundle:
- [protocol.md](./references/protocol.md) — spec revision, transports, lifecycle, primitives, result shapes, annotations, SDKs.
- [tool-design.md](./references/tool-design.md) — Anthropic's effective-tools guidance, naming, structured output, errors, context budget, code execution.
- [security.md](./references/security.md) — the threat model, OAuth 2.1 authorization, hardening, supply chain, OWASP MCP Top 10.
- [maintenance.md](./references/maintenance.md) — versioning, deprecation, `list_changed`, toolsets, pagination, observability, ops, pitfalls.
- [testing.md](./references/testing.md) — the Inspector, the stderr rule, test layers, eval-driven tool optimization.
- [publishing.md](./references/publishing.md) — the registry, `server.json`, distribution channels, the consumer config block, MCPB.
## Source
Based on [How to Build an MCP Server](https://saschb2b.com/blog/how-to-build-mcp-server), widened to the full lifecycle against the MCP `2025-11-25` spec. Reference implementations at [godot-mcp](https://github.com/Vollkorn-Games/godot-mcp) and [aseprite-mcp](https://github.com/Vollkorn-Games/aseprite-mcp).
Files in this package (13)
- CARD.manifest.json 1 KB
- CARD.md 5 KB
- CARD.md.sigstore 4 KB
- CARD.svg 6 KB
- SKILL.md 9 KB
- permissions.yaml 1 KB
- references/index.md 2 KB
- references/maintenance.md 8 KB
- references/protocol.md 11 KB
- references/publishing.md 5 KB
- references/security.md 9 KB
- references/testing.md 4 KB
- references/tool-design.md 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · saschb2b/skills | 100 | MIT |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
| rrezartprebreza/spring-boot-skills | 100 | MIT |
| rrezartprebreza/spring-boot-skills | 100 | MIT |
| lynricsy/hyperskills | 100 | MIT |
| market0v0/shipkit | 100 | MIT |
| hoblin/claude-ruby-marketplace | 100 | MIT |
| Amey-Thakur/AI-SKILLS | 90 | MIT |
Database snapshot: 13.11.2026 · package version 04455be2ec71 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mcp-ops
Model Context Protocol server development, tool design, resource handling, and transport configuration. Use for: mcp, model context protocol, mcp server, mcp tool, mcp resource, fastmcp, mcp transport, stdio, sse, streamable http, mcp inspector, tool handler, mcp prompt. - 100mcp
MCP (Model Context Protocol) servers and clients: tools, resources, prompts, stdio/HTTP transport, OAuth, tool poisoning. Use for writing a server or fixing a client. - 100build-mcp-server
Use when exposing a service or dataset to AI clients through the Model Context Protocol — few task-shaped tools with typed inputs, read-only by default, server-enforced confirmation for writes, stdio or Streamable HTTP, OAuth for remote, size limits, tests with the Inspector. - 100mcp-servers
Builds, secures and tests Model Context Protocol (MCP) servers - choosing MCP vs a CLI or API, tools, resources and prompts, stdio vs Streamable HTTP transport, task-shaped tool design, logging rules, OAuth for remote servers, input validation, testing with the MCP Inspector,… - 100mcp-server-security
Security-first Agent Skill for Model Context Protocol (MCP) server security: design, harden, threat-model, audit, and test stdio or Streamable HTTP MCP servers. Use for MCP security checklists, OAuth resource authorization, prompt injection and tool poisoning, SSRF, least… - 100mcp-builder
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…