Skip to main content

8.2 MCP server development

What MCP is for​

The Model Context Protocol is an open protocol between a host/client (Claude Code, Claude Desktop, your application, the API's MCP connector) and a server that exposes capabilities. Its value is reuse and independent maintenance: one server, many clients, its own release cycle.

The published sample item

An internal inventory REST API must be reachable from several Claude applications and maintained independently of any one of them → build an MCP server exposing the inventory operations as tools. Hard-coding the logic into each app's prompt is neither reusable nor maintainable; pasting inventory data into context gives no live access and wastes the window; built-in tools do not reach arbitrary internal APIs.

The three primitives​

PrimitiveControlled byPurposeExample
ToolsThe model decides to call themActions and queries with side effects or parameterscheck_stock, create_reservation
ResourcesThe client/application selects and supplies themReadable context identified by URIinventory://warehouses/eu-1/policy
PromptsThe user invokes themParameterised prompt templatesA "stock reconciliation report" template

Choosing between them is a real item shape: something the model should decide to do is a tool; static context the app should attach is a resource; a workflow a person starts is a prompt.

Transports and topology​

TransportShapeFits
stdioThe client launches the server as a subprocess and speaks over stdin/stdoutLocal, single-user, co-located with the developer's machine or the agent process. Simplest and most common for Claude Code
Remote (HTTP/SSE)A long-lived networked server the client connects toShared team infrastructure, centrally deployed and versioned, authenticated per user
ConsiderationstdioRemote
DeploymentNothing to hostReal service, with uptime and rollout concerns
AuthInherits the local user's environmentNeeds its own authentication and per-user authorization
SharingPer machineOne deployment for everyone
CredentialsLocal environment variablesServer-side secret manager
Failure modeProcess crash, visible locallyNetwork, availability, rate limits

Authoring notes​

Whatever SDK you use, the same design rules decide quality:

RuleDetail
Descriptions are the interfaceSame standard as any tool: purpose, when to use, when not to, formats, prerequisites, return shape, errors (8.1)
Schemas constrain the inputTyped, described, enum where closed, additionalProperties: false
Return curated resultsThe fields the model needs — an MCP tool that returns a 200-field payload poisons the window
Structured errorsCategory plus retryability plus an actionable message, not a stack trace
Own the authorizationThe server enforces what the calling identity may do; it cannot trust the model or the client
Secrets from the environmentNever in the server's tool descriptions, arguments, or responses
Idempotent write operationsClients retry
Version the surfaceTool names and schemas are a contract; renaming one breaks every consumer
Log every callIdentity, tool, arguments, outcome

Test it against ambiguous requests, not happy paths: if two of your tools could plausibly answer the same phrasing, the descriptions are not done.

Integrating with Claude applications​

ClientConfiguration
Claude Code.mcp.json in the repo for shared servers (committed; use environment-variable expansion for credentials), user config for personal ones. Both can be active at once
Claude DesktopDesktop connector configuration, per user
Claude Agent SDKMCP servers declared in the options object
Claude API (MCP connector)mcp_servers: [{type: "url", url, name}] and tools: [{type: "mcp_toolset", mcp_server_name: "<same name>"}], with beta mcp-client-2025-11-20. Both halves are required — one alone is a validation error

MCP tools arrive in the model's window as ordinary tool definitions, so everything from 8.1 applies: they compete for selection with your local tools, they cost prefix tokens, and a badly described MCP tool degrades an otherwise good tool set. Trust boundary: an MCP server's output is untrusted data — it can carry injected instructions (7.1).

Quiz​

  1. Question 1

    A team needs Claude to call an internal inventory service exposed as a REST API. They want the capability to be reusable across several Claude applications and maintained independently of any one app. Which approach best fits?