MCP
Also known as: Model Context Protocol
Standardises how an agent host discovers and calls tools across vendors over JSON-RPC.
Claude Code
- Add MCP servers to `~/.claude/settings.json` under
mcpServers; Claude Code callslist_toolson session start and the catalog is immediately available. - Allowlist each server's tools in
permissions.allowvia `settings.json` to avoid per-call prompts for trusted servers. - Review the allow-list periodically — stale entries from removed servers accumulate silently and expand the permission surface without active use.
- Prefer project-level
~/.claude/settings.jsonfor project-specific servers; global~/config for servers used across all projects.
Primitives
Related patterns
Cursor
- Add servers to
.cursor/mcp.json(project) or~/.cursor/mcp.json(global) in themcpServersobject withcommandandargs. - Remote servers use a
urlfield instead ofcommand; Cursor handles OAuth automatically for marketplace-installed servers. - Enable auto-run for trusted servers in Cursor settings to avoid per-call approval prompts during Agent sessions.
- Review
.cursor/mcp.jsonwhen removing servers — Cursor does not automatically remove stale tool entries from the active session.
Primitives
Related patterns
Decision
| Use when ✓ | Avoid when ✗ |
|---|---|
| +Best for cases where the same set of tools must be reachable from more than one host (a desktop assistant, an IDE, a custom agent) and writing the integration once per host is wasted effort. | −When the agent has one host, one tool backend, and one team owns both, the protocol overhead buys nothing the local function-calling SDK does not already provide. |
| +Justified where the tool catalog needs to grow without a host release. A server team can add a tool and every connected host sees it on the next list_tools call. | −Without an authentication and authorization story for remote servers (OAuth scopes, allow-listed origins, audit logs), exposing tools over HTTP is a wider attack surface than a same-process function call. |
| +A good fit when the host and the tool backend are owned by different teams, vendors, or companies, and a typed wire format is the cheapest contract between them. | −When the tools require streaming bidirectional state the spec does not yet codify, falling back to a custom WebSocket protocol is honest; pretending to be MCP-compliant while breaking the contract corrupts the ecosystem. |
| +Better than a hand-rolled tool registry when you want users to install third-party servers (a Postgres connector, a GitHub connector, a Slack connector) the same way they install browser extensions. |
In the wild
| Source | Claim |
|---|---|
| github.com → | Anthropic ships Claude Desktop with a built-in MCP client and publishes a reference filesystem, git, postgres, and brave-search server set so a user can wire any of them into the assistant by editing one config file. |
| blog.cloudflare.com → | Cloudflare runs MCP servers on Workers behind an OAuth provider, demonstrating the remote-server deployment shape (public URL, scoped access, no local install) and ships an OAuth helper library other server authors can adopt. |
| openai.github.io → | OpenAI Agents SDK ships first-class MCP server support, letting a Python agent connect to any compliant server and consume its tools without per-server adapter code, on the explicit reasoning that the protocol is becoming the cross-vendor default. |
Reader gotcha
Invariant Labs documented a tool-poisoning attack in which a malicious MCP server hides instructions inside tool descriptions or in fields the host renders without showing to the user; on next session the agent reads the description, follows the embedded instructions, and exfiltrates data the user never authorised. The protocol does not sanitise descriptions: tool metadata is untrusted input the host must classify and gate before showing it to the model. source
Implementation sketch
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'
const server = new Server(
{ name: 'fs-server', version: '0.1.0' },
{ capabilities: { tools: {} } },
)
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [{
name: 'read_file',
description: 'Read a file from disk',
inputSchema: {
type: 'object',
properties: { path: { type: 'string' } },
required: ['path'],
},
}],
}))
server.setRequestHandler(CallToolRequestSchema, async (req) => {
if (req.params.name === 'read_file') {
const { readFile } = await import('node:fs/promises')
const path = req.params.arguments?.path as string
return { content: [{ type: 'text', text: await readFile(path, 'utf-8') }] }
}
throw new Error(`Unknown tool: ${req.params.name}`)
})
await server.connect(new StdioServerTransport())
export {}
- LangChain
- LangGraph
- OpenAI Agents
- Mastra
- Google ADK
References
- DOCSMCP architecture
Model Context Protocol (MCP) is an open standard, published by Anthropic in November 2024, for how an agent host talks to external tools and data sources. The protocol fixes the wire format (JSON-RPC 2.0 over stdio for local servers, streamable HTTP for remote ones), the handshake (capability negotiation on connect), and three primitives a server can expose: tools the agent can invoke, resources the agent can read, and prompts the agent can substitute into its own context. Anything that follows the spec is wire-compatible with anything else that does, regardless of which model sits on the host side or which backend sits behind the server.
Background · context and trade-offs
The point of the protocol is the inverse of bespoke tool integration. Without MCP, every host re-implements the connector for every backend it wants to expose; with MCP, a single server is written once and consumed by any compliant host. Discovery is server-side: the host calls list_tools and receives the JSON-schema-typed catalog at runtime, so the host never knew the schema in advance and the server can publish a new tool without a host release. Capability negotiation lets the two sides agree on which features apply to a given session (sampling, roots, streaming) and the host adapts.
MCP sits next to but distinct from Tool Use / ReAct, the runtime loop that decides when to invoke a tool. Tool Use is the consumer-side pattern; MCP is the integration substrate the consumer reads from. They compose: the ReAct agent picks an action from the catalog the MCP client returned, the client dispatches the JSON-RPC call, the result comes back as an observation, and the loop continues. The cost is operational. Local stdio servers run with the privileges of the host process; remote HTTP servers need OAuth, scope review, and a threat model for payloads hidden in tool descriptions or returned content. The protocol handles the wire; the deployment handles the trust.