Skip to content
Skills Library
AI & agents · Building & coding

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

Repository
skills ↗
Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
13
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

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

  1. Target the current protocol
  2. Step 1: Pick the transport
  3. Step 2: The five layers
  4. Step 3: Identify the bridge — this decides everything else
  5. Step 4: Write ONE tool end to end before anything else
  6. Writing tools agents actually use
  7. Extending without breaking agents
  8. Security non-negotiables
  9. Test, debug, publish
  10. Reference bundle
Original SKILL.md headings · 99 lines, 1,145 words
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

RepositoryScoreLicence
This page · saschb2b/skills100MIT
nimadorostkar/Claude-Skills-collection100MIT
rrezartprebreza/spring-boot-skills100MIT
rrezartprebreza/spring-boot-skills100MIT
lynricsy/hyperskills100MIT
market0v0/shipkit100MIT
hoblin/claude-ruby-marketplace100MIT
Amey-Thakur/AI-SKILLS90MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.