When Anthropic introduced the Model Context Protocol (MCP) in November 2024, the initial reception was muted. Another protocol from another AI company, developers thought. Six months later, MCP had become one of the fastest-adopted developer protocols in recent memory, with over 5,000 MCP servers published on GitHub and major IDE vendors — including Cursor, Windsurf, and the VS Code team — shipping native MCP support. By mid-2026, MCP has achieved what few developer standards accomplish: genuine ecosystem momentum that makes it the de facto standard for connecting AI models to the outside world.
This guide provides a comprehensive technical introduction to MCP, covering the protocol architecture, the most important server implementations available today, and a complete walkthrough of building your own MCP server.
What Is MCP?
The Model Context Protocol is an open standard that defines a structured communication interface between AI applications (called hosts) and external data sources and tools (called servers). Think of it as USB-C for AI integrations — a single standardized connector that allows any compliant AI application to communicate with any compliant tool or data source.
Before MCP, the AI integration landscape was fragmented. Each AI product implemented its own function-calling interface, each tool integration required custom code, and developers were forced to rewrite integrations when switching models or platforms. Claude had tools. OpenAI had function calling. LangChain had its own tool abstraction. None of them talked to each other.
MCP solves this by defining a protocol layer that any AI application can implement on the host side, and that tool developers implement on the server side. A single MCP server that provides access to your PostgreSQL database can be connected to Claude Desktop, Cursor, your custom Python agent, and a Slack bot — with zero additional integration work.
Design Principles
MCP was designed with several explicit principles:
1. Local-first, extensible to remote: MCP servers can run as local processes (for security-sensitive tools) or as remote services. The protocol supports both without requiring different client implementations.
2. Stateful connections: Unlike REST APIs, MCP connections maintain state across multiple requests, enabling tools that require session management (authenticated API clients, database connections, browser sessions).
3. Capability negotiation: Hosts and servers exchange capability information at connection time, allowing graceful degradation when a host doesn't support all server capabilities.
4. Security boundaries: The protocol explicitly separates read-only resources from executable tools, allowing host applications to implement different approval flows for each.
Architecture Deep Dive
The Three-Layer Model
MCP's architecture separates concerns into three layers:
┌─────────────────────────────────────────────────────┐
│ MCP HOST │
│ (Claude Desktop / Cursor / Custom App) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ MCP │ │ MCP │ │ MCP │ │
│ │ Client 1 │ │ Client 2 │ │ Client 3 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼───────────────┼───────────────┼─────────────┘
│ │ │
(stdio/SSE) (stdio/SSE) (stdio/SSE)
│ │ │
┌───────▼──────┐ ┌──────▼───────┐ ┌────▼─────────┐
│ MCP Server │ │ MCP Server │ │ MCP Server │
│ (Filesystem)│ │ (Database) │ │ (Web APIs) │
└──────────────┘ └──────────────┘ └──────────────┘
Host: The AI application that wants to use external capabilities. Hosts manage multiple MCP client connections and route tool calls to appropriate servers.
Client: The protocol implementation within the host. Each client maintains a 1:1 connection with a server and handles the protocol-level communication.
Server: An independent process or service that exposes capabilities through the MCP protocol. Servers are the units of functionality that developers build and share.
Transport Mechanisms
MCP supports two primary transport mechanisms:
stdio (Standard Input/Output): The server runs as a child process of the host. Communication happens through the process's stdin and stdout streams. This is the most common transport for local servers — it's simple, requires no port configuration, and provides natural security isolation.
Server-Sent Events (SSE): For remote servers, MCP uses HTTP with Server-Sent Events for server-to-client communication and regular HTTP POST for client-to-server communication. This enables hosted MCP services accessible over the network.
The Three Primitive Types
MCP servers can expose three types of capabilities:
1. Tools: Executable functions that the AI can call. Tools can have side effects (writing files, making API calls, executing code). The host application is expected to request user approval before executing tools with significant side effects.
{
"name": "create_file",
"description": "Creates a new file with specified content",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "File path to create" },
"content": { "type": "string", "description": "File content" }
},
"required": ["path", "content"]
}
}
2. Resources: Read-only data that the AI can access. Resources are URI-addressable and can represent anything from local files to live API responses.
{
"uri": "postgres://mydb/schema/users",
"name": "Users Table Schema",
"description": "Schema definition for the users table",
"mimeType": "application/json"
}
3. Prompts: Reusable prompt templates that users can invoke. Prompts are a higher-level abstraction that allow server authors to encode common workflows.
{
"name": "analyze_pr",
"description": "Analyze a GitHub pull request for potential issues",
"arguments": [
{ "name": "pr_url", "description": "GitHub PR URL", "required": true }
]
}
The Message Protocol
MCP uses JSON-RPC 2.0 as its message format. A typical tool call flow:
1. Initialization
// Client → Server
{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": { "protocolVersion": "2024-11-05",
"capabilities": { "roots": { "listChanged": true } },
"clientInfo": { "name": "ClaudeDesktop", "version": "1.0" } } }
// Server → Client
{ "jsonrpc": "2.0", "id": 1, "result": {
"protocolVersion": "2024-11-05",
"capabilities": { "tools": {}, "resources": {} },
"serverInfo": { "name": "MyServer", "version": "1.0" } } }
2. Tool Discovery
// Client → Server
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
// Server → Client
{ "jsonrpc": "2.0", "id": 2, "result": { "tools": [...] } }
3. Tool Execution
// Client → Server
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": { "name": "create_file",
"arguments": { "path": "/tmp/test.txt", "content": "Hello!" } } }
// Server → Client
{ "jsonrpc": "2.0", "id": 3, "result": {
"content": [{ "type": "text", "text": "File created successfully" }] } }
Major MCP Servers Worth Knowing
The MCP ecosystem has exploded with community-built servers. Here are the most impactful:
Official Anthropic Servers
Filesystem: Read, write, and navigate the local filesystem. The gateway to AI-powered file management.
Git: Full Git operations — status, diff, commit, branch management. Essential for developer workflows.
Fetch: Fetch and parse web content. Enables AI agents to retrieve documentation, APIs, and web pages.
Memory: A key-value store with semantic search. Provides persistent memory across agent sessions.
Database Servers
PostgreSQL MCP: Read-only access to PostgreSQL with schema inspection. Allows AI to query your database and understand its structure without write permissions.
SQLite: Full SQLite access with transaction support. Popular for local development and testing.
Prisma MCP: Works with your existing Prisma schema to give AI tools type-safe database access with full awareness of your data model.
Development Tool Servers
GitHub: Full GitHub API integration — browse repos, create PRs, read issues, manage projects. One of the most widely used MCP servers.
Docker: Manage containers, images, and Docker Compose projects. AI can spin up test environments, check container logs, and manage deployments.
Kubernetes: kubectl operations through MCP. AI-assisted cluster management and debugging.
Sentry: Access error traces, performance data, and issue details. Dramatically speeds up debugging workflows.
Productivity and Data Servers
Notion: Read and write Notion pages, databases, and workspaces.
Slack: Send messages, read channels, search conversations.
Google Drive: File access and management.
Linear: Project management and issue tracking.
Browser Automation
Playwright: Full browser control through Playwright. The key enabler for web scraping, E2E test generation, and visual testing workflows.
Puppeteer: Alternative browser automation using Puppeteer.
Building Your Own MCP Server
Now for the hands-on portion. We'll build a complete MCP server in Python that provides AI agents with access to a weather API and a local SQLite cache. This covers the core patterns you'll use in real MCP server development.
Setup
mkdir weather-mcp-server
cd weather-mcp-server
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install mcp httpx sqlite3
Server Implementation
# server.py
import asyncio
import json
import sqlite3
from datetime import datetime, timedelta
from typing import Any
import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import (
Tool,
TextContent,
Resource,
ResourceContents,
)
# Initialize MCP server
app = Server("weather-server")
# SQLite cache setup
def init_db():
conn = sqlite3.connect("weather_cache.db")
conn.execute("""
CREATE TABLE IF NOT EXISTS weather_cache (
city TEXT PRIMARY KEY,
data TEXT NOT NULL,
cached_at TEXT NOT NULL
)
""")
conn.commit()
conn.close()
def get_cached_weather(city: str) -> dict | None:
conn = sqlite3.connect("weather_cache.db")
row = conn.execute(
"SELECT data, cached_at FROM weather_cache WHERE city = ?",
(city.lower(),)
).fetchone()
conn.close()
if row:
cached_at = datetime.fromisoformat(row[1])
# Cache valid for 30 minutes
if datetime.now() - cached_at < timedelta(minutes=30):
return json.loads(row[0])
return None
def cache_weather(city: str, data: dict):
conn = sqlite3.connect("weather_cache.db")
conn.execute(
"""INSERT OR REPLACE INTO weather_cache (city, data, cached_at)
VALUES (?, ?, ?)""",
(city.lower(), json.dumps(data), datetime.now().isoformat())
)
conn.commit()
conn.close()
# Tool definitions
@app.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(
name="get_weather",
description="Get current weather conditions for a city. "
"Returns temperature, humidity, wind speed, and conditions.",
inputSchema={
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name (e.g., 'London', 'Tokyo', 'New York')"
},
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature units (default: celsius)",
"default": "celsius"
}
},
"required": ["city"]
}
),
Tool(
name="get_forecast",
description="Get a 5-day weather forecast for a city.",
inputSchema={
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"days": {
"type": "integer",
"description": "Number of days (1-5, default: 5)",
"minimum": 1,
"maximum": 5,
"default": 5
}
},
"required": ["city"]
}
),
Tool(
name="clear_cache",
description="Clear the weather cache for a specific city or all cities.",
inputSchema={
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City to clear (omit to clear all)"
}
}
}
)
]
# Tool implementations
@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
if name == "get_weather":
return await handle_get_weather(arguments)
elif name == "get_forecast":
return await handle_get_forecast(arguments)
elif name == "clear_cache":
return await handle_clear_cache(arguments)
else:
raise ValueError(f"Unknown tool: {name}")
async def handle_get_weather(args: dict) -> list[TextContent]:
city = args["city"]
units = args.get("units", "celsius")
# Check cache first
cached = get_cached_weather(city)
if cached:
data = cached
source = "cache"
else:
# Fetch from API (using Open-Meteo, which is free)
async with httpx.AsyncClient() as client:
# First, geocode the city
geo_response = await client.get(
"https://geocoding-api.open-meteo.com/v1/search",
params={"name": city, "count": 1}
)
geo_data = geo_response.json()
if not geo_data.get("results"):
return [TextContent(type="text", text=f"City not found: {city}")]
location = geo_data["results"][0]
lat, lon = location["latitude"], location["longitude"]
# Fetch weather
weather_response = await client.get(
"https://api.open-meteo.com/v1/forecast",
params={
"latitude": lat,
"longitude": lon,
"current": [
"temperature_2m", "relative_humidity_2m",
"wind_speed_10m", "weather_code"
],
"temperature_unit": "fahrenheit" if units == "fahrenheit" else "celsius"
}
)
weather_data = weather_response.json()
current = weather_data["current"]
data = {
"city": location.get("name", city),
"country": location.get("country", ""),
"temperature": current["temperature_2m"],
"humidity": current["relative_humidity_2m"],
"wind_speed": current["wind_speed_10m"],
"weather_code": current["weather_code"],
"units": units
}
cache_weather(city, data)
source = "api"
unit_symbol = "°F" if units == "fahrenheit" else "°C"
result = (
f"Weather for {data['city']}, {data['country']} (from {source}):\n"
f" Temperature: {data['temperature']}{unit_symbol}\n"
f" Humidity: {data['humidity']}%\n"
f" Wind Speed: {data['wind_speed']} km/h\n"
)
return [TextContent(type="text", text=result)]
async def handle_get_forecast(args: dict) -> list[TextContent]:
city = args["city"]
days = args.get("days", 5)
async with httpx.AsyncClient() as client:
geo_response = await client.get(
"https://geocoding-api.open-meteo.com/v1/search",
params={"name": city, "count": 1}
)
geo_data = geo_response.json()
if not geo_data.get("results"):
return [TextContent(type="text", text=f"City not found: {city}")]
location = geo_data["results"][0]
forecast_response = await client.get(
"https://api.open-meteo.com/v1/forecast",
params={
"latitude": location["latitude"],
"longitude": location["longitude"],
"daily": ["temperature_2m_max", "temperature_2m_min",
"precipitation_sum", "weather_code"],
"forecast_days": days
}
)
forecast = forecast_response.json()["daily"]
result_lines = [f"5-Day Forecast for {location['name']}, {location['country']}:"]
for i in range(min(days, len(forecast["time"]))):
result_lines.append(
f"\n{forecast['time'][i]}:\n"
f" High: {forecast['temperature_2m_max'][i]}°C "
f" Low: {forecast['temperature_2m_min'][i]}°C\n"
f" Precipitation: {forecast['precipitation_sum'][i]}mm"
)
return [TextContent(type="text", text="\n".join(result_lines))]
async def handle_clear_cache(args: dict) -> list[TextContent]:
city = args.get("city")
conn = sqlite3.connect("weather_cache.db")
if city:
conn.execute("DELETE FROM weather_cache WHERE city = ?", (city.lower(),))
message = f"Cache cleared for {city}"
else:
conn.execute("DELETE FROM weather_cache")
message = "All cache entries cleared"
conn.commit()
conn.close()
return [TextContent(type="text", text=message)]
# Resource definitions (read-only data the AI can access)
@app.list_resources()
async def list_resources():
return [
Resource(
uri="weather://cache/summary",
name="Weather Cache Summary",
description="Summary of currently cached weather data",
mimeType="text/plain"
)
]
@app.read_resource()
async def read_resource(uri: str) -> ResourceContents:
if uri == "weather://cache/summary":
conn = sqlite3.connect("weather_cache.db")
rows = conn.execute(
"SELECT city, cached_at FROM weather_cache ORDER BY cached_at DESC"
).fetchall()
conn.close()
if rows:
summary = "Cached cities:\n" + "\n".join(
f" {row[0]}: cached at {row[1]}" for row in rows
)
else:
summary = "No weather data currently cached."
return ResourceContents(
uri=uri,
mimeType="text/plain",
text=summary
)
raise ValueError(f"Unknown resource: {uri}")
# Main entry point
async def main():
init_db()
async with stdio_server() as streams:
await app.run(
streams[0],
streams[1],
app.create_initialization_options()
)
if __name__ == "__main__":
asyncio.run(main())
Connecting to Claude Desktop
To connect your server to Claude Desktop, add it to the configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"weather": {
"command": "/path/to/your/venv/bin/python",
"args": ["/path/to/weather-mcp-server/server.py"]
}
}
}
Restart Claude Desktop, and you'll see your weather tools available in the conversation interface.
Connecting to Cursor
In Cursor settings, navigate to Extensions > MCP Servers and add:
{
"weather-server": {
"command": "python",
"args": ["/path/to/weather-mcp-server/server.py"]
}
}
Publishing Your MCP Server
To share your server with the community:
# Create a proper entry point
# Add a pyproject.toml
pip install build
python -m build
# Publish to PyPI
pip install twine
twine upload dist/*
For Node.js servers (the other common MCP implementation language), publish to npm with the mcp-server- prefix convention.
Production MCP Server Patterns
Authentication Handling
For servers that need to authenticate with external services:
import os
from mcp.server import Server
app = Server("authenticated-server")
# Read credentials from environment variables, never hardcode
API_KEY = os.environ.get("MY_SERVICE_API_KEY")
@app.list_tools()
async def list_tools():
if not API_KEY:
# Return empty tool list if not configured
return []
return [...] # Your tools
Error Handling Best Practices
from mcp.types import TextContent, McpError
from mcp.types import INVALID_PARAMS, INTERNAL_ERROR
@app.call_tool()
async def call_tool(name: str, arguments: dict):
try:
# Validate required arguments
if "required_field" not in arguments:
raise McpError(INVALID_PARAMS, "required_field is missing")
result = await do_the_work(arguments)
return [TextContent(type="text", text=result)]
except httpx.TimeoutException:
raise McpError(INTERNAL_ERROR, "External API timeout. Please retry.")
except httpx.HTTPStatusError as e:
raise McpError(INTERNAL_ERROR, f"API error: {e.response.status_code}")
Streaming for Long-Running Operations
For tools that produce output over time (like running shell commands or watching log streams), MCP supports streaming responses through server-sent events in the SSE transport mode.
The MCP Ecosystem in 2026
The MCP ecosystem has matured significantly:
Registries: The MCP Registry lists thousands of community-built servers, searchable by category and language.
Testing: The mcp-inspector tool provides a browser-based interface for testing MCP servers interactively.
Hosted MCP: Services like Smithery.ai and mcp.run offer hosted MCP infrastructure, allowing you to deploy servers as managed services without managing infrastructure.
Enterprise adoption: Major enterprises including Microsoft, Salesforce, and Atlassian have published official MCP servers for their platforms. MCP is increasingly the expected interface for enterprise AI integrations.
Standard evolution: MCP 2025-03 (the current stable version as of this writing) added streaming support and improved resource handling. The specification is maintained openly at modelcontextprotocol.io.
MCP vs. Alternatives
| MCP | OpenAI Function Calling | LangChain Tools | REST APIs | |
|---|---|---|---|---|
| Cross-platform | Yes | No (OpenAI-specific) | Partial | Yes |
| Stateful connections | Yes | No | Partial | No |
| Resource access | Yes | No | No | N/A |
| Ecosystem size | Large (5K+ servers) | Medium | Large | Massive |
| Local server support | Yes | No | Limited | No |
| Open standard | Yes | No | No | Yes |
MCP's killer advantage is the ecosystem effect: build one MCP server, and it works with every MCP-compatible host — including Claude Desktop, Cursor, Windsurf, your custom agents, and any future hosts that adopt the protocol.
Conclusion
MCP has achieved something rare in developer tooling: it solved a genuine pain point (AI integration fragmentation) with an elegant protocol that was practical enough to see rapid adoption. The ecosystem has reached the critical mass where building an MCP server is a better investment than building a custom integration for each AI platform.
For developers building AI-integrated applications, MCP should be your default integration interface. For teams building internal tools, publishing them as MCP servers makes them instantly available to your entire AI toolchain. And for platform teams, adopting MCP compatibility is increasingly a table-stakes requirement for enterprise AI initiatives.
The weather server walkthrough above is a complete, production-ready starting point. Adapt the pattern to your data sources, APIs, or internal services — and you'll have a reusable AI integration that works across the entire MCP ecosystem.
For more AI development tutorials and protocol guides, visit TechPulse's Developer Trends section.