Building an MCP Server

ai mcp llm claude-curated

The Model Context Protocol (MCP) is an open protocol that lets an LLM application talk to external tools and data through one uniform interface — instead of every app hand-rolling a bespoke integration for every service. Write an MCP server once and any MCP-capable client (a chat app, a coding agent, an IDE) can use it.

Core concepts

• Server / client / transport — the server exposes capabilities; the client (the LLM host) consumes them. Transports are typically stdio (local subprocess) or streamable HTTP / SSE (remote).
• Three primitives:
  • Tools — model-invoked functions (the model decides to call them). This is where most of the value is.
  • Resources — readable data the client can pull into context (files, records).
  • Prompts — reusable, parameterised prompt templates.

When to build one (vs just calling the API)

Build a server when you want a capability reused across many agent sessions or clients, when the model should decide when to call it, or when you want a clean auth/guardrail boundary. If it’s a one-off script step, a direct API call is simpler — don’t reach for MCP reflexively.

Wrapping an existing REST/Graph API

The common shape is “turn an API I already have into agent tools”:

1. Map endpoints → tools, but not 1:1. Collapse chatty call sequences into task-shaped tools (find_available_slot beats exposing five raw calendar endpoints). The model reasons better about intent-level tools.
2. Design tool schemas with tight, well-described parameters — the description IS the prompt the model reads. Ambiguous schemas cause wrong calls.
3. Auth — OAuth or token exchange at the server boundary; never make the model handle credentials. For remote servers, scope tokens narrowly.
4. Handle pagination, rate limits, and partial failure inside the tool — return a clean summarised result, not a raw 3,000-line payload the model has to wade through.

Design lessons

• Return model-friendly output — structured, compact, with the salient fields first. Token budget is real.
• Separate read from write — mark mutating tools clearly and consider requiring confirmation; an agent that can silently delete is a liability.
• Fail loud and specific — “not found: no calendar for user X” lets the model recover; a bare 500 makes it loop.
• Version your tool surface — renaming a tool breaks every client’s learned behaviour.

Related: Agentic Dev Workflows, OAuth Redirect URL Management.