mcp-server-building
Design, implement, harden, and verify Model Context Protocol (MCP) servers with precise tool contracts, least-privilege authorization, safe transports, structured errors, and interoperability tests. Use when creating a new MCP server, exposing an API or data source through MCP, reviewing an MCP server design, adding or revising MCP tools, or preparing an MCP server for production.
git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills /tmp/mcp-server-building && cp -r /tmp/mcp-server-building/agent-engineering/mcp-server-building ~/.claude/skills/mcp-server-buildingSKILL.md
# MCP Server Building Build the smallest server that exposes the required capability safely. Treat protocol conformance, business authorization, and model behavior as separate concerns; all three need independent controls. ## Inputs Collect or infer, and label assumptions for, these inputs: - User jobs and the minimum capabilities needed - Backing APIs, data stores, file systems, or local processes - Intended MCP clients, exact protocol revision, and current SDK/runtime constraints - Local `stdio` or remote HTTP transport requirements - Tenant, identity, credential, and authorization model - Read, write, destructive, billable, or externally visible effects - Expected volume, latency, pagination, and deployment environment - Existing schemas, tests, observability, and incident procedures Ask only for missing facts that materially change the architecture. Consult the current MCP specification and SDK documentation before relying on version-sensitive behavior. ## Output contract Deliver: 1. A server design stating scope, trust boundaries, transport, identity flow, and explicit non-goals 2. A tool catalog with names, descriptions, structural input/output/error schemas, explicit effect and data-class arrays, authorization mode, idempotency, and error behavior 3. Implementation or a file-level implementation plan, according to the user's requested scope 4. Unit, integration, authorization, and protocol-interoperability tests 5. Verification evidence: commands run, relevant results, and anything not verified 6. Deployment, rollback, monitoring, and credential-revocation guidance 7. Residual risks and decisions that still require an owner Use [assets/server-design-template.md](assets/server-design-template.md) when a design artifact is useful. Use [scripts/validate_tool_manifest.py](scripts/validate_tool_manifest.py) to lint a JSON tool manifest before implementation or review. ## Workflow ### 1. Bound the capability Translate the user job into a narrow set of resources, prompts, and tools. Prefer one clear operation per tool. Exclude administrative or broad pass-through operations unless the use case requires them. Identify every effect; a tool can have more than one. Record reads, creates, updates, deletes, execution, external communication, financial transactions, access changes, and network egress separately. Classify every data flow, including public, internal, confidential, restricted, personal, financial, health, and credential data. Do not compress this inventory into a single "read" or "write" label. ### 2. Model trust and authority Draw the path from MCP host to server to downstream service. State which component authenticates the actor, which authorizes the operation, where credentials live, and which data is untrusted. Do not rely on the model, the tool description, or a client-side confirmation as the sole authorization control. Enforce object-, tenant-, and action-level authorization at the server or downstream service. ### 3. Design tool contracts - Use stable, action-oriented names and unambiguous descriptions. - Constrain input schemas with types, enums, bounds, formats, and required fields. - Reject unknown or malformed fields when compatibility permits. - Define a structural `outputSchema` and return matching `structuredContent`; do not substitute a prose description of the result shape. - Define stable caller-safe error codes and structural error-data schemas; keep secrets and internals out of errors. - Add pagination, bounded limits, timeouts, and cancellation where operations may grow. - State whether writes are idempotent and support idempotency keys where retries can duplicate effects. - Separate read operations from write or destructive operations so clients can grant narrower authority. Read [references/server-design-checklist.md](references/server-design-checklist.md) for contract, transport, and test details. ### 4. Implement the server Use an official or well-maintained SDK compatible with the selected protocol revision. For new work, verify the current stable revision before coding; as of 2026-08-09 it is `2026-07-28`. That revision is stateless at the protocol layer: implement `server/discover`, carry version/client capabilities in per-request `_meta`, include required routing headers for Streamable HTTP, and do not introduce `initialize`, `notifications/initialized`, or `Mcp-Session-Id`. Support a legacy handshake only on an explicitly tested older-revision compatibility path. Return the required `resultType` on every result. Implement `input_required` plus retry-bound `inputResponses`/`requestState` for Multi Round-Trip Requests when mid-call input is needed. Return deterministic, cacheable listings with revision-required cache metadata. Apply deadlines, bounded concurrency, safe retries with jitter, connection cleanup, and structured logging. Emit correlation IDs and outcome metadata without logging tokens, secrets, full prompts, or sensitive records. ### 5. Enforce authorization and consent Declare an authorization mode for every tool, including an explicit `public` mode for genuinely unauthenticated tools. For local `stdio`, source credentials from an approved environment or secret store; never embed them in arguments, source, or logs. For remote HTTP, follow the current MCP authorization specification, HTTPS requirements, exact redirect and issuer validation, token audience validation, short-lived credentials, and least-privilege scopes. Never pass an MCP client token unchanged to an upstream API. Obtain a separate downstream token with the correct audience. Bind approvals to the exact action and parameters for consequential tools. ### 6. Verify behavior Run all of the following that apply: - Structural manifest lint with `validate_tool_manifest.py`; treat warnings as review prompts and never present a passing lint as protocol conformance or safety certification - SDK type checks and unit tests for pure business logic - For `2026
Design reproducible evaluations for AI agents with representative task sets, explicit rubrics, appropriate graders, baselines, regression gates, and failure analysis. Use when defining agent quality, comparing prompts or models, validating a release, measuring tool-use reliability, investigating regressions, or deciding whether an agent is ready for production.
Design privacy-aware observability for AI agents using traces, spans, structured events, metrics, cost attribution, dashboards, alerts, and investigation workflows. Use when instrumenting an agent, debugging intermittent tool or model failures, defining service-level objectives, analyzing latency or spend, auditing agent decisions, or preparing production monitoring.
Design and verify auditable human oversight, approval gates, escalation paths, and safe state transitions for AI agent workflows. Use when deciding which agent actions require review, adding approve/reject or dual-control flows, preventing unauthorized autonomous effects, creating decision records, reducing rubber-stamping, or recovering safely from rejected, expired, or failed actions.
Design and operate bounded multi-agent workflows with task decomposition, dependency graphs, ownership, handoff contracts, shared-state controls, approvals, recovery, and synthesis. Use when a task contains genuinely independent workstreams, specialized roles, parallel research or implementation, reviewer-worker loops, or coordination problems that one agent should not execute sequentially.
Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and realistic tests. Use when creating function-calling tools, MCP tools, agent actions, structured tool inputs, or when a model selects the wrong tool, invents arguments, or causes unsafe side effects.
Plan, execute, document, and retest authorized security assessments of AI agents and multi-agent workflows using safe adversarial cases, synthetic identities, canaries, and evidence-based findings. Use when defining red-team rules of engagement, assessing prompt injection or excessive agency, testing tool and identity boundaries, evaluating memory or cross-agent attacks, scoring a campaign, or verifying remediation in an approved environment.
Threat-model and harden AI agents, RAG systems, assistants, and tool-using workflows against direct, indirect, stored, cross-agent, and multimodal prompt injection. Use when reviewing an agent architecture, isolating untrusted content, constraining tools and egress, protecting secrets, adding injection-focused tests, investigating a suspected injection incident, or documenting residual prompt-injection risk.
Audit agent skills, plugins, prompts, manifests, scripts, dependencies, and bundled assets for provenance, prompt-injection, permission, execution, exfiltration, persistence, and update risk. Use when evaluating a third-party skill before installing, enabling, updating, publishing, or distributing it; reviewing an untrusted SKILL.md, agent configuration, MCP integration, archive, or repository; comparing a package with a known-good version; or investigating unexpected tool, network, credential, or filesystem behavior.