MCP Server Building

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 when a design artifact is useful. Use 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 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.