MCP is an open protocol that standardises how LLMs talk to external systems — the USB-C of AI. This guide covers: the problem it solves, architecture, three primitives (Tools/Resources/Prompts), 12 popular servers, Claude Desktop and Claude Code setup, building your own MCP server in 50 lines, security layers and the ecosystem outlook.
TL;DR — MCP in 5 sentences
MCP = Model Context Protocol — an open protocol that standardises the conversation between LLMs and external systems (files, DBs, APIs).
Announced by Anthropic in November 2024 as an open standard; quickly adopted by Cursor, Windsurf, Zed, VS Code and others.
The core problem it solves: N models × M data sources = N×M custom integrations. MCP reduces it to N + M.
Three building blocks: Tools (functions the model can call), Resources (data the model can read), Prompts (reusable templates).
Runs on JSON-RPC 2.0; transported via stdio or HTTP+SSE.
A modern developer wants to connect Postgres to Claude. Then Notion. Then GitHub, then their internal CRM… Each one is custom code to expose as a 'tool' to Claude. The same person moves to ChatGPT — and rewrites everything. Then to Cursor — rewrite again. That's the N models × M sources = N×M integrations problem. 5 models + 10 sources = 50 different integrations. MCP collapses this to N + M: write one Postgres MCP server, and every MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, Zed) can use it. Anthropic open-sourced the protocol to be 'the USB-C of AI ecosystems' — independent of who made what, every device talks the same standard.
Old: N models × M sources
MCP: N models + M MCP servers
Write once, used everywhere
Section 02
Architecture — Host, Client, Server, Transport
MCP has three roles. (1) Host — the user-facing app: Claude Desktop, Claude Code (CLI), Cursor, Windsurf, Zed. A host can connect to many MCP servers at once. (2) Client — the connection layer inside the host; one client instance per server. (3) Server — a small program that 'exposes' a tool or data source over MCP: filesystem MCP, github MCP, postgres MCP. Transport (the carrier) has two options: stdio (host launches the server as a subprocess; JSON-RPC over stdin/stdout) — ideal for local tools; HTTP+SSE — for remote servers, with Server-Sent Events for streaming. Standard JSON-RPC 2.0 messages on the wire: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get.
Host (Claude Desktop)
Client
Transport (stdio/SSE)
Server (Postgres MCP)
Data source
Section 03
Three primitives — Tools, Resources, Prompts
An MCP server can offer three things, giving the model three different capabilities. Tools — functions the model can call. Things like 'execute_sql_query(query)', 'create_github_issue(title, body)'. Each tool has a JSON Schema for its input; the model reads it and calls with the right shape. Resources — data sources the model can read. URI-based: 'postgres://customers/123', 'file:///docs/policy.md'. Think Tools = 'action,' Resources = 'content.' Prompts — reusable prompt templates. A server defines an 'analyze_codebase' prompt; the user picks it in the host, fills params, and the model runs with the prepared template. Together: for a RAG assistant you can package Tools (search), Resources (docs), and Prompts (query template) — all in a single MCP server.
Section 04
Ecosystem — which clients, which servers?
Client adoption has been fast. Anthropic: Claude Desktop (most mature MCP integration), Claude Code (CLI auto-discovers MCP servers). Third-party: Cursor (native MCP), Windsurf (MCP marketplace), Zed editor, VS Code (via the Continue extension), Visual Studio. Official MCP servers (50+ in modelcontextprotocol/servers): filesystem (local files), github (issues/PRs/repos), postgres + sqlite (SQL), slack (read/send messages), brave-search and fetch (web), google-drive, sentry (errors), puppeteer (browser automation). Community: thousands — Linear, Notion, Asana, Jira, Stripe, AWS, Kubernetes, Docker, Datadog. Discover via marketplaces like mcp.so and glama.ai.
Section 05
Practical setup — Claude Desktop and Claude Code examples
To add an MCP server in Claude Desktop: Settings → Developer → Edit Config. That opens claude_desktop_config.json. Write an 'mcpServers' object: { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/Documents"] } }. Restart Claude Desktop and the filesystem tools appear. Claude Code is even simpler: in the terminal run `claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path`. `claude mcp list` shows installed servers. Cursor exposes a Settings → MCP UI. Important: servers run on your local machine — anything the server can do, you've given Claude. Be careful with the filesystem server: if you pass '/', Claude can touch your whole disk.
Section 06
Build your own MCP server — TypeScript SDK
Writing an MCP server is surprisingly small. Skeleton in TypeScript: install '@modelcontextprotocol/sdk'. Import Server and create an instance. Use setRequestHandler() for 'tools/list' and 'tools/call'. Each tool is { name, description, inputSchema (JSON Schema) }. On tools/call, match by name, run the work, return the result. Use StdioServerTransport for stdio; one line starts it. 50 lines of TypeScript and you've exposed your company's internal API as an MCP server — today your Claude Desktop can talk to it. The Python SDK ('mcp' package) is just as easy. One key pattern: write tool descriptions VERY clearly — the model reads them to decide when to call. Vague description = wrong tool call.
Section 07
Security — sandbox, scope, user approval
MCP connects the model to your machine — powerful and risky. Think in four layers. (1) Sandbox: restrict what paths a server can access (pass /Documents to filesystem, not /). (2) Tool whitelisting: some hosts (Claude Desktop) let you pre-approve which tools auto-run. (3) User approval: the host asks before each tool call — 'Claude wants to write this file, allow?' Think twice before saying 'always allow' in production. (4) Secrets: keep API keys in env vars; don't log them when passing them to the server. Critical: an MCP server could be malicious — just like npm packages. Install only from sources you trust (the official modelcontextprotocol org, verified maintainers).
Section 08
MCP vs alternatives — Function Calling, Plugins, RAG
MCP is new but not alone in chasing similar goals. Function Calling (OpenAI / Anthropic SDKs): the model sees tool schemas and calls them. Difference from MCP: function defs live in YOUR code; switching models means rewriting. With MCP the definition lives in the server, model-agnostic. ChatGPT Plugins (2023): you provide an OpenAPI spec. Difference: plugins work only inside ChatGPT, MCP works across any compatible host. RAG: document search + context injection. MCP isn't an alternative to RAG, it's complementary — you can put a 'rag_search' tool inside an MCP server and call it from any client. Rule of thumb: local-tool integration = MCP; staying inside one model SDK = Function Calling; pure web/RAG = built-in features may be enough.
Section 09
Real-world uses — 5 practical scenarios
When does MCP show its value? Five examples. (1) Software developer: Cursor + GitHub MCP + Sentry MCP — Claude sees the bug in code, opens a GitHub issue, pulls the relevant stacktrace from Sentry, suggests a fix. (2) Data analyst: Claude Desktop + Postgres MCP + Slack MCP — 'What sold most in the last 7 days?', Claude writes SQL, posts the result to #ops on Slack. (3) Content writer: Claude + Notion MCP + Drive MCP — reads drafts in Notion, saves finals to Drive. (4) Operations: Claude Desktop + Jira MCP + Linear MCP — works through assigned tickets, updates status. (5) Internal customer support: Claude Code + custom company-API MCP server + RAG — the agent talks to your knowledge base and customer data with proper access controls.
Section 10
Future — why MCP is a turning point
MCP's growth in just months isn't accidental — the protocol fills a real need. Expected in late 2025 / 2026: (1) MCP marketplaces (mcp.so, glama, smithery) — npm-like discovery and distribution. (2) Enterprise certification and audit standards — 'this MCP server cleared our security policy' badges. (3) Hosted MCP servers — Vercel/Cloudflare-style 'MCP edge deployment' services. (4) MCP-native apps — SaaS products built MCP-first from day one (CRMs marketing themselves as 'MCP-first'). (5) Browser MCP — a Chrome extension standard that lets Claude talk to your web pages. By 2026, understanding MCP will be a core capability for anyone shipping AI products.
Popular MCP Servers
12 servers you can use today
The most-used 12 from the official modelcontextprotocol/servers repo. All install via `npx -y @modelcontextprotocol/server-X`.
A minimal TypeScript server exposing a 'lookup_customer' tool from your company API. Build it, run `npm run build`, and add it to your Claude Desktop config.
Prompt
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: "company-crm", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "lookup_customer",
description: "Looks up a customer record by customer ID or email. Does not include order history; use lookup_orders for that.",
inputSchema: {
type: "object",
properties: {
customer_id: { type: "string", description: "UUID or email" }
},
required: ["customer_id"]
}
}
]
}));
server.setRequestHandler(CallToolRequestSchema, async (req) => {
if (req.params.name === "lookup_customer") {
const id = req.params.arguments?.customer_id as string;
// Replace with a real DB call: const cust = await db.customers.find(id);
return {
content: [{ type: "text", text: JSON.stringify({ id, name: "Sample User", tier: "gold" }) }]
};
}
throw new Error("Unknown tool: " + req.params.name);
});
const transport = new StdioServerTransport();
await server.connect(transport);
Tool descriptions matter more than you think
The model reads this text to decide when to call. Instead of 'fetches a customer,' write 'Looks up a customer record by customer ID or email. Does not include order history; use lookup_orders for that.' — clear and bounded.
Frequently asked questions
How does MCP differ from OpenAI Function Calling?
Function Calling is bound to one model SDK — OpenAI tool defs live in your code, and switching to Anthropic means rewriting. MCP is model-agnostic: write a server once and use it from Claude, Cursor, Windsurf, Zed and any compatible host. MCP also adds Resources and Prompts on top of Tools.
How does MCP relate to RAG?
Not rivals — complements. RAG is a technique (search + context injection). MCP is a protocol (model ↔ tool conversation). You can package a RAG system as an MCP server: a 'rag_search' tool + document resources + query prompts — then use that RAG from any MCP host.
Should I write the server in Python or TypeScript?
Both have official SDKs. If you live in the JS ecosystem, TypeScript SDK ships faster (npx makes distribution easy). If your data/ML pipelines are in Python, the Python SDK is natural — pandas, requests etc. The wire protocol is identical; pick whichever you write more fluently.
Is MCP self-hostable?
MCP is self-host by default — servers run on YOUR machine (stdio) or your own server (HTTP+SSE). No data goes to Anthropic/OpenAI; the host (Claude Desktop) ↔ server traffic is local. The model API side is separate — anything the model actually processes does go to the model provider. For sensitive data: Ollama + a local MCP setup keeps data fully on-prem.
How do I test an MCP server?
Anthropic's MCP Inspector is the official tool — run `npx @modelcontextprotocol/inspector` and exercise your server from a UI. Perfect for manually exercising tools/list, tools/call, resources/list. Always Inspect before shipping to production.
What if no MCP client supports my workflow?
You can still write the server; pull a client sample from anthropic-mcp Python examples and test against it. Or use 'mcp-bridge' style proxies (e.g. mcp-proxy) to expose the server as an HTTP API for any client. The ecosystem is growing fast — by 2026 it'll be hard to find an AI client that doesn't support MCP.
Next steps with MCP
This guide is the map. For practice see the Claude Code hub, for connecting automation chains the n8n learning path, for end-to-end internal RAG + MCP server see Enterprise AI Modules.