MCP — Model Context Protocol

Overview

MCP is an open protocol from Anthropic that standardizes how AI agents discover and use tools, access resources, and receive prompts from external servers. It enables a universal interface between AI models and the systems they interact with.

Architecture

code

Host (Claude, VS Code, IDE)
  └── Client (maintains 1:1 connection)
        └── Server (exposes tools, resources, prompts)

Core Primitives

Tools

Functions the agent can call:

json

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

Resources

Data the agent can read (files, database records, API responses):

json

{
  "uri": "file:///project/config.json",
  "name": "Project Configuration",
  "mimeType": "application/json"
}

Prompts

Reusable prompt templates the server can offer:

json

{
  "name": "summarize",
  "description": "Summarize a document",
  "arguments": [
    { "name": "content", "description": "Text to summarize", "required": true }
  ]
}

Transport Options

Transport	Use Case
stdio	Local servers running as child processes
Streamable HTTP	Remote servers over HTTP with SSE streaming

Building an MCP Server (Python)

python

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")

@mcp.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Sunny, 72°F in {city}"

@mcp.resource("config://app")
def get_config() -> str:
    """Return application configuration."""
    return '{"theme": "dark", "lang": "en"}'

Building an MCP Server (TypeScript)

typescript

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

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

server.tool("get_weather", { city: z.string() }, async ({ city }) => ({
  content: [{ type: "text", text: `Sunny, 72°F in ${city}` }],
}));

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

Client Configuration

Configure MCP servers in Claude Desktop or Claude Code:

json

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "weather_server"],
      "env": { "API_KEY": "..." }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

Lifecycle

•Initialize — client and server exchange capabilities
•Discover — client lists available tools, resources, prompts
•Invoke — client calls tools, reads resources, uses prompts
•Notify — server sends change notifications (resource updates, tool list changes)

Best Practices

•Keep tool descriptions clear and specific — the AI model uses them to decide when to call tools.
•Use JSON Schema for inputSchema with required fields for type safety.
•Return structured data (JSON) from tools when possible for downstream processing.
•Use resources for read-only data access and tools for actions with side effects.
•Implement proper error handling — return error content rather than throwing exceptions.
•Use stdio transport for local development and Streamable HTTP for production deployments.
•Version your server capabilities so clients can adapt to changes.