MCP
Unpacked

MCP is USB-C for AI. Before USB-C every gadget had its own charger; now one port fits all. Before MCP every AI app needed its own connector for Figma, GitHub or Jira; now a tool ships one MCP server and every MCP app can use it.

Without a standard, M apps times N tools means M × N integrations. MCP turns that into M clients plus N servers. Anthropic released it in November 2024; in December 2025 it moved to the Agentic AI Foundation under the Linux Foundation. Claude, ChatGPT, VS Code, Cursor and many others speak it.

Think of a hotel. The host is the front desk you talk to. Each client is a phone line from the desk to one service. Each server is a service: the kitchen, the laundry, the taxi desk. You never call the kitchen yourself; the desk does it for you.

The host (Claude Code, Claude Desktop, an IDE) runs the model, holds the conversation and enforces consent. It creates one MCP client per server, keeping each connection isolated. Servers are small programs, local processes or remote URLs, that expose capabilities. The model never talks to a server directly; the host decides what to send and when.

A workshop has power tools you operate (tools), reference books on the shelf (resources) and printed recipe cards for common jobs (prompts). The model uses the tools, the app hands it books to read, and you choose which recipe to follow.

Tools are model controlled functions with a JSON Schema input and optional outputSchema; results return content plus structuredContent. Resources are app controlled data addressed by URI (file:///, postgres://), with templates and change subscriptions. Prompts are user controlled templates, usually shown as slash commands. Servers can also ask the user for input through elicitation. Roots, sampling and logging are deprecated in 2026-07-28.

Like a waiter with a menu. The kitchen hands over its menu (tools/list). You say what you want; the waiter decides which dish matches, checks with you if it is pricey, sends the order (tools/call) and brings the plate back so you can carry on.

The host lists tools and gives their names, descriptions and schemas to the model. The model emits a tool use with arguments; the host checks permissions and may ask you; the client sends tools/call; the server validates input, runs, and returns content with resultType complete, or input_required to ask for more. The host appends the result to the conversation and the model continues, often calling more tools.

Each message is a self addressed envelope: it says which protocol version it speaks and what the sender can do, so any server instance can answer it without remembering earlier letters.

Requests have jsonrpc, id, method and params; results or errors come back with the same id; notifications have no id. In 2026-07-28 the initialize handshake and sessions are gone: params._meta carries io.modelcontextprotocol/protocolVersion, clientCapabilities and clientInfo. Servers must implement server/discover. Results include resultType (complete or input_required), and list results add ttlMs and cacheScope for caching. Servers on 2025-11-25 still use initialize; SDKs handle both.

stdio is an intercom between two rooms in the same house: fast and private. Streamable HTTP is a phone line to another city: anyone with the number and permission can call.

With stdio the host launches the server as a child process and exchanges newline delimited JSON-RPC on stdin and stdout; stderr is for logs. Streamable HTTP uses one endpoint: the client POSTs each message, with MCP-Protocol-Version, Mcp-Method and Mcp-Name headers, and the server answers with JSON or an SSE stream for progress and long results. HTTP+SSE (two endpoints) is deprecated; use mcp-remote to bridge stdio only hosts to remote servers.

Like a hotel key card. Reception checks who you are once and gives you a card that opens only your room for a limited time. You never give the room your passport.

An MCP server is an OAuth resource server. A 401 points the client to Protected Resource Metadata, which names the authorization server. The client registers (Client ID Metadata Documents preferred; dynamic client registration is deprecated), opens your browser for login with PKCE, receives tokens bound to that server (resource indicators), and sends Authorization: Bearer on every request. stdio servers usually read API keys from environment variables instead.

Adding a server is like adding a contact. Local keeps it in your phone for one project, project shares it with the team through the repo, and user makes it available in every project you open.

claude mcp add name -- command adds a stdio server; --transport http adds a remote URL. --scope local (default, in ~/.claude.json for this project), project (.mcp.json in the repo, approved on first use) or user (all your projects). Tools appear as mcp__server__tool, resources are referenced with @server:uri, and prompts become /mcp__server__prompt. Outputs over 10,000 tokens warn and MAX_MCP_OUTPUT_TOKENS sets the cap; MCP_TIMEOUT sets startup timeout.

Instead of describing a design over the phone, you hand the developer the actual blueprint with exact measurements, colours and the names of parts already in your kit.

Figma's remote server lives at https://mcp.figma.com/mcp with OAuth, or install the Figma plugin for Claude Code, which bundles the server and skills. A desktop server runs at http://127.0.0.1:3845/mcp for some enterprise cases. Tools include get_design_context (code ready structure for a frame or selection), get_variable_defs (tokens), get_screenshot, get_metadata and Code Connect mappings to your real components.

Like having the project board, the code review queue and the build screen open beside your editor, with an assistant who can read and update them for you.

Microsoft's server runs locally with npx @azure-devops/mcp <org>; on first use it signs you in through the browser, or reuses az login with --authentication azcli. Limit tools with domains such as core, work, work-items, repositories and pipelines. A hosted remote server at https://mcp.dev.azure.com/{org} is in preview, but Microsoft currently recommends the local server for Claude Code because of Entra ID sign in support.

Your Postman workspace becomes a shared notebook of every API you use. Claude can look up the exact request and response instead of guessing from memory.

Postman hosts the server at https://mcp.postman.com with three modes: minimal (essential tools, default), code (for generating client code from API definitions) and mcp (the full toolset). Use OAuth where the host supports it, or an API key in a Bearer header; an EU endpoint exists at mcp.eu.postman.com. A local server runs with npx @postman/postman-mcp-server and POSTMAN_API_KEY.

GitHub gives Claude a desk in your code review room. Playwright gives it hands and eyes in a browser, so it can click through the page it just built and see what breaks.

GitHub's official remote server at https://api.githubcopilot.com/mcp/ signs in with OAuth and covers repos, issues, PRs and Actions, with toolsets to limit scope. Microsoft's Playwright server (npx @playwright/mcp@latest) controls a browser through accessibility snapshots rather than screenshots, which is fast and reliable. Reference servers such as filesystem, git, fetch and memory live in modelcontextprotocol/servers.

Writing a server is like opening a small shop counter: put up a sign saying what you offer (the description), say what you need from customers (the schema), and serve them (the handler).

The TypeScript SDK gives you McpServer plus registerTool, registerResource and registerPrompt. Inputs use Zod; outputs return content and, with an outputSchema, structuredContent. Use StdioServerTransport for local use or the Streamable HTTP transport behind Express for remote. The v1 package is @modelcontextprotocol/sdk; newer v2 packages track the 2026-07-28 spec, so check the SDK README for your version.

Write a normal Python function, put a sticker on it saying "tool", and FastMCP handles the rest: the schema from your type hints, the description from your docstring, and the protocol.

The mcp package's FastMCP class gives decorators: @mcp.tool(), @mcp.resource("uri") and @mcp.prompt(). Type hints and Pydantic models become JSON Schema, docstrings become descriptions, and return values become content (and structured output when typed). mcp.run() defaults to stdio; transport="streamable-http" serves HTTP. uv makes running it simple.

Test the shop counter yourself before opening the doors: walk up, read the sign, place an order, check the receipt. Only then let real customers, the models, in.

The MCP Inspector (npx @modelcontextprotocol/inspector) opens a web UI to list and call tools, read resources and see raw JSON-RPC; --cli scripts the same checks for CI. In Claude Code, claude mcp list and /mcp show status, claude --debug prints MCP connection details, and MCP_TIMEOUT raises the startup limit for slow servers. Common faults: logging to stdout, wrong paths (use absolute), missing env vars, and huge outputs.

The MCP ecosystem is a well stocked hardware store: kits to build your own (SDKs), a testing bench (Inspector), sample builds to copy (reference servers) and a catalogue of what others made (the registry).

Official SDKs cover TypeScript, Python, Java, Kotlin, C#, Go, PHP, Ruby, Rust and Swift. The MCP Registry at registry.modelcontextprotocol.io is the open catalogue of public servers, published with the mcp-publisher CLI and a server.json. modelcontextprotocol/servers holds reference servers. Vendors publish official servers (GitHub, Figma, Postman, Microsoft, Playwright), and community lists help with discovery; review any server before trusting it.

Giving an AI tools is like giving a new assistant keys. Hand over only the keys they need, check before they open the safe, and remember that a note slipped under the door is not an order from you.

Main risks: prompt injection (a web page, issue or email tells the model to do something else), tool poisoning (a malicious server hides instructions in descriptions), over broad tokens, and data leaving through another tool. Defences: install trusted servers only and pin versions, use read only or scoped tokens, keep write and delete tools behind confirmation, separate secrets from shared config, validate inputs server side, and never pass tokens through to upstream APIs.

Design tools like a good restaurant menu: a few clear dishes, each described in plain words, served in sensible portions, and a waiter who explains when something is unavailable.

Model a few high level tasks rather than wrapping every API endpoint. Use verb_noun names and say in the description what it does, when to use it and when not to. Keep parameters few, typed and described, with enums for fixed choices. Return only what is needed, paginate, and prefer human readable ids. Errors should explain how to fix the call. Mark tools with annotations and keep tools/list order stable for caching.