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.
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
| Primitive | Controlled by | Purpose | Example |
|---|---|---|---|
| Tools | The model decides to call them | Actions and queries with side effects or parameters | check_stock, create_reservation |
| Resources | The client/application selects and supplies them | Readable context identified by URI | inventory://warehouses/eu-1/policy |
| Prompts | The user invokes them | Parameterised prompt templates | A "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
| Transport | Shape | Fits |
|---|---|---|
| stdio | The client launches the server as a subprocess and speaks over stdin/stdout | Local, 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 to | Shared team infrastructure, centrally deployed and versioned, authenticated per user |
| Consideration | stdio | Remote |
|---|---|---|
| Deployment | Nothing to host | Real service, with uptime and rollout concerns |
| Auth | Inherits the local user's environment | Needs its own authentication and per-user authorization |
| Sharing | Per machine | One deployment for everyone |
| Credentials | Local environment variables | Server-side secret manager |
| Failure mode | Process crash, visible locally | Network, availability, rate limits |
Authoring notes
Whatever SDK you use, the same design rules decide quality:
| Rule | Detail |
|---|---|
| Descriptions are the interface | Same standard as any tool: purpose, when to use, when not to, formats, prerequisites, return shape, errors (8.1) |
| Schemas constrain the input | Typed, described, enum where closed, additionalProperties: false |
| Return curated results | The fields the model needs — an MCP tool that returns a 200-field payload poisons the window |
| Structured errors | Category plus retryability plus an actionable message, not a stack trace |
| Own the authorization | The server enforces what the calling identity may do; it cannot trust the model or the client |
| Secrets from the environment | Never in the server's tool descriptions, arguments, or responses |
| Idempotent write operations | Clients retry |
| Version the surface | Tool names and schemas are a contract; renaming one breaks every consumer |
| Log every call | Identity, 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
| Client | Configuration |
|---|---|
| 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 Desktop | Desktop connector configuration, per user |
| Claude Agent SDK | MCP 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
- 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?