Model Context Protocol (MCP): The Complete Developer Guide

What Is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that defines how AI models communicate with external tools, data sources, and services. It provides a universal interface so that any MCP-compatible AI client (Claude Code, Cursor, Windsurf, Cline) can use any MCP server without writing custom integration code for each combination.

MCP was created by Anthropic and open-sourced in November 2024. It has since been adopted by virtually every major AI coding tool, making it the de-facto standard for AI tool integration. As of 2026, there are thousands of community and official MCP servers available.

Think of MCP as the USB standard for AI tools. Before USB, every peripheral needed a unique connector. USB gave everything a common interface. MCP does the same for AI integrations: instead of every AI tool building its own GitHub integration, Slack integration, and database integration separately, any tool that speaks MCP can use any MCP server.

How MCP Works: Architecture Overview

An MCP integration involves three components:

┌─────────────────────────────────────────────────────────────┐
│  MCP HOST (the AI client)                                    │
│  Claude Code, Cursor, Windsurf, Cline                       │
│                                                             │
│  ┌──────────────┐          ┌──────────────────────────────┐ │
│  │  MCP Client  │ ◄──────► │  MCP Server (external tool)  │ │
│  └──────────────┘  stdio/  │  - Filesystem, GitHub        │ │
│                    HTTP    │  - PostgreSQL, Puppeteer      │ │
│                            │  - Custom tools              │ │
│                            └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

• MCP Host: The AI application that wants to use external tools (Claude Code, Cursor, etc.)
• MCP Client: Built into the host; manages connections to MCP servers
• MCP Server: An external process that exposes tools, resources, or prompts to the AI

Communication happens over either:

• stdio (standard input/output) for local servers
• HTTP with Server-Sent Events (SSE) for remote servers

The AI model doesn't call external APIs directly. It invokes MCP tools through the standardized protocol, and the MCP server handles the actual API call, database query, or filesystem operation.

The Three Capabilities: Tools, Resources, Prompts

MCP servers can expose three types of capabilities:

Tools (Callable Functions)

Tools are functions the AI can invoke. They're the most commonly used MCP capability.

Example — a database MCP tool:

{
  "name": "query_database",
  "description": "Execute a read-only SQL query against the project database",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": { "type": "string", "description": "The SQL query to execute" }
    },
    "required": ["sql"]
  }
}

The AI model calls this tool by name, passing the sql argument. The MCP server executes the query and returns the results. The AI never writes raw database connection code — it just calls a typed, validated tool.

Resources (Readable Data)

Resources are data sources the AI can read. Unlike tools (which perform actions), resources expose data — files, database records, API responses, or streams.

{
  "uri": "file:///project/CLAUDE.md",
  "name": "Project context file",
  "mimeType": "text/markdown"
}

The AI can read this resource directly, getting the current contents of CLAUDE.md without needing filesystem tool calls.

Prompts (Reusable Templates)

Prompts are pre-written instructions that the AI (or user) can invoke by name. Useful for consistent task templates:

{
  "name": "code_review",
  "description": "Run a structured code review on the specified file",
  "arguments": [
    { "name": "file_path", "required": true }
  ]
}

Invoking this prompt gives the AI a consistent set of code review instructions, ensuring every review follows the same standards.

Setting Up MCP in Claude Code

Claude Code has first-class, official MCP support. Configuration lives in .claude/mcp.json in your project directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

With this configuration:

• Claude Code can read/write files in the allowed directory via the filesystem server
• Claude Code can run SQL queries against your PostgreSQL database
• Claude Code can create PRs, read issues, and browse code on GitHub

Start a Claude Code session and Claude automatically connects to the configured MCP servers. You can then give instructions like: "Query the database for all users created in the last 30 days and create a GitHub issue summarizing the growth."

For a step-by-step setup guide, see Connecting MCP Servers to Claude Code, Cursor & Cline.

Official MCP Servers You Should Know

Anthropic and the community maintain a growing catalog of MCP servers at github.com/modelcontextprotocol/servers. The most useful for developers:

See MCP Server Examples and Use Cases for a practical breakdown of when to use each.

Building a Custom MCP Server

When existing servers don't cover your use case, you can build your own. Anthropic provides SDKs for TypeScript and Python.

Here's a minimal MCP server in TypeScript that exposes one tool:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-api-server",
  version: "1.0.0",
});

server.tool(
  "get_project_status",
  "Get the current deployment status of a project",
  {
    project_id: z.string().describe("The project ID to check"),
  },
  async ({ project_id }) => {
    // Call your internal API
    const response = await fetch(`https://api.internal/projects/${project_id}/status`);
    const data = await response.json();
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

This server:

1. Defines a get_project_status tool with a typed project_id argument
2. When the AI calls the tool, it fetches from your internal API
3. Returns the result as text for the AI to process

For a complete walkthrough, see How to Build an MCP Server: Step-by-Step.

MCP vs Traditional API Integration

Before MCP, AI tools integrated with external services through two approaches:

1. The AI writes code that calls the API — indirect and error-prone (wrong endpoints, incorrect authentication, missing error handling)
2. Tool definitions in the model's system prompt — each tool custom-built, no standard, lots of duplication

MCP improves on both:

The key insight: with MCP, you write the integration once (as an MCP server) and every MCP-compatible AI tool can use it. See MCP vs Traditional APIs for AI Tools for a deep comparison.

Security Model and Best Practices

MCP has a clear security model:

Local servers are isolated. When you run an MCP server locally via stdio, it only has access to what you give it. The filesystem server, for example, takes an explicit path argument — it cannot access files outside that path.

Remote MCP servers require authentication. HTTP-based MCP servers should use OAuth 2.0 or API key authentication. Anthropic's MCP specification includes an OAuth extension specifically for remote servers.

The AI only has access to what the server exposes. If your PostgreSQL MCP server only exposes a query_database read-only tool, Claude Code cannot execute DROP TABLE — because that tool doesn't exist in the server's tool list.

Key security practices:

1. Scope filesystem servers narrowly. Don't point the filesystem server at /. Point it at the specific project directory.
2. Use read-only database credentials when possible. The AI generally only needs to read data.
3. Validate inputs in your MCP server. Even though MCP has schema validation, add business-logic validation for security-sensitive operations.
4. Audit what tools you expose. Every tool exposed to the AI is a potential attack surface if an adversarial prompt injection occurs.

See Securing MCP Servers: Best Practices for a complete security guide.

MCP in Cursor, Windsurf, and Cline

MCP is not exclusive to Claude Code — it's an open standard adopted across the ecosystem:

Cursor: Supports MCP servers via the mcp section of ~/.cursor/mcp.json or the project-level .cursor/mcp.json. Cursor's implementation follows the official spec closely.

Windsurf: MCP support via Settings → MCP. Windsurf has a GUI for adding/removing servers without editing JSON manually.

Cline: Full MCP support via the VS Code extension settings. Cline was an early adopter of the MCP standard and has comprehensive documentation.

The configuration format differs slightly between tools, but the underlying servers are the same — you write one MCP server and it works in Claude Code, Cursor, Cline, and Windsurf. This is the key value of the open standard.

Key Takeaways

• MCP is the open standard for AI ↔ external tool communication — write once, use in any AI client
• Servers expose three capability types: Tools (callable functions), Resources (readable data), Prompts (templates)
• Claude Code has official first-class MCP support via .claude/mcp.json
• Official servers exist for PostgreSQL, GitHub, filesystem, browser control, Slack, and more
• Building a custom server requires only a few dozen lines of TypeScript or Python
• Security model: local servers are isolated, remote servers need auth, scope everything narrowly
• All major AI coding tools (Claude Code, Cursor, Windsurf, Cline) support MCP

MCP is the infrastructure layer that makes AI coding agents genuinely useful beyond file editing. The ability to query your database, create GitHub PRs, or control a browser — all directly from Claude Code, with type safety and permission control — is what separates capable agentic workflows from basic AI autocomplete.

Related: How to Build an MCP Server: Step-by-Step · Connecting MCP Servers to Claude Code, Cursor & Cline · Claude Code MCP Servers: What They Are & How to Use