Apr 12, 2026 · 6 min read

Last updated on Sep 7, 2026

MCP Complete Developer Guide — Architecture, Servers, Clients, and Production (2026)

Q: How do I build an MCP server?

Use the official `@modelcontextprotocol/sdk` package (TypeScript) or `mcp` package (Python). Define your tools, resources, and prompts, then connect via stdio or SSE transport. A basic server with one tool can be built in under 50 lines of code. *Related: What is MCP? · Build an MCP Server (TypeScript) · MCP Security Risks · MCP vs A2A vs ACP*

MCP (Model Context Protocol) is the standard for connecting AI applications to external tools and data. This guide covers everything: architecture, building servers, connecting clients, security, and production deployment.

If you’re new to MCP, start with our What is MCP? explainer.

MCP should not be confused with agent-session or plugin packaging protocols. VS Code’s Agent Host Protocol synchronizes sessions between a host and its clients, while Agent Plugins 1.0 can package skills and MCP server configuration for compatible agent clients. See VS Code Agent Host and Agent Plugins 1.0 explained for how those layers fit together.

Architecture

Browser-resident website tools are a separate integration choice from a remote MCP server. Our agent-ready websites with WebMCP guide covers the current ChatGPT browser API, authenticated page context, permission boundaries and fallback testing.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  MCP Host    │     │  MCP Client │     │  MCP Server  │
│  (Claude,    │────▶│  (built into│────▶│  (your code) │
│   Cursor)    │     │   the host) │     │              │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
                                        ┌─────────────┐
                                        │  Your tool,  │
                                        │  API, or DB  │
                                        └─────────────┘

Hosts are AI applications that users interact with. Claude Desktop, Cursor, VS Code, and Claude Code are all MCP hosts.

Clients are protocol handlers built into hosts. They manage connections to servers, handle message routing, and enforce security boundaries. One host can connect to multiple servers.

Servers are what you build. They expose capabilities (tools, resources, prompts) to any MCP-compatible host through a standardized interface.

A real-world example: COROS training data

COROS illustrates why “supports MCP” does not describe one universal permission model. Its consumer connector lets an athlete authorize a compatible host such as ChatGPT or Claude to read selected training and health data without writing integration code. That path is currently read-only. COROS separately offers self-service OAuth 2.0 developer access, including documented training-plan writes, and a reviewed commercial partner API with multi-user OAuth, webhooks and two-way platform integration.

For developers, the lesson is to document the product path as carefully as the protocol: identify who authorizes the server, whose records it can access, which tools are read-only, which can mutate state, and whether commercial multi-user use requires a separate agreement. An MCP endpoint does not automatically inherit every capability of the provider’s underlying API. COROS documents these boundaries in its consumer connection guide, self-service data access guide, and partner API documentation.

The three primitives

Tools — actions the AI can take

server.tool("send_slack_message", {
  channel: z.string(),
  message: z.string()
}, async ({ channel, message }) => {
  await slack.chat.postMessage({ channel, text: message });
  return { content: [{ type: "text", text: `Sent to ${channel}` }] };
});

The AI decides WHEN to call a tool based on the user’s request. The host shows the user what tool is being called and asks for approval (unless in auto mode).

Resources — data the AI can read

server.resource("user_profile", "user://{userId}", async (uri) => {
  const user = await db.users.findById(uri.params.userId);
  return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(user) }] };
});

Resources are read-only data sources. The AI can browse and read them but can’t modify them through the resource interface.

Prompts — reusable templates

server.prompt("code_review", { language: z.string(), code: z.string() }, ({ language, code }) => ({
  messages: [{
    role: "user",
    content: `Review this ${language} code for bugs, security issues, and improvements:\n\n${code}`
  }]
}));

Prompts are pre-built templates that users can invoke. They standardize common workflows.

Transport layers

MCP supports two transport mechanisms:

stdio — Server runs as a subprocess. Host communicates via stdin/stdout. Best for local servers.

SSE (Server-Sent Events) — Server runs as an HTTP service. Host connects via HTTP. Best for remote/shared servers.

// stdio transport (local)
const server = new McpServer({ name: "my-server", version: "1.0.0" });
server.connect(new StdioServerTransport());

// SSE transport (remote)
server.connect(new SSEServerTransport("/messages", response));

Building your first MCP server

TypeScript

npm init -y
npm install @modelcontextprotocol/sdk zod

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: "demo-server", version: "1.0.0" });

// Define a tool
server.tool("get_weather", { city: z.string() }, async ({ city }) => {
  const weather = await fetch(`https://wttr.in/${city}?format=j1`).then(r => r.json());
  return { content: [{ type: "text", text: `${city}: ${weather.current_condition[0].temp_C}°C` }] };
});

// Connect via stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Python

pip install mcp

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("demo-server")

@server.tool()
async def get_weather(city: str) -> str:
    """Get current weather for a city."""
    import httpx
    resp = await httpx.AsyncClient().get(f"https://wttr.in/{city}?format=j1")
    data = resp.json()
    return f"{city}: {data['current_condition'][0]['temp_C']}°C"

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

import asyncio
asyncio.run(main())

See our detailed tutorials: Build an MCP Server in TypeScript and Build an MCP Server in Python.

Connecting to hosts

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/your/server.js"]
    }
  }
}

Claude Code

claude mcp add my-server node /path/to/server.js

Cursor

Settings → MCP → Add Server → point to your server binary.

Security considerations

MCP servers have access to whatever you give them — databases, APIs, file systems. Security is critical:

Principle of least privilege — Only expose what the AI needs
Input validation — Validate all tool parameters with Zod/Pydantic
Authentication — Use OAuth or API keys for remote servers
Sandboxing — Run servers in containers for isolation
Audit logging — Log every tool call for review

See our MCP Security Risks and MCP Security Checklist guides.

MCP in the ecosystem

MCP is one of three AI protocols gaining adoption:

Protocol	Purpose	Creator
MCP	AI ↔ Tools (vertical)	Anthropic → Linux Foundation
A2A	Agent ↔ Agent (horizontal)	Google → Linux Foundation
ACP	Agent communication	Community-driven

Most production systems use MCP for tool access and A2A for multi-agent coordination. See our protocol comparison.

Production checklist

Input validation on all tool parameters
Error handling with meaningful messages
Rate limiting for expensive operations
Authentication for remote servers
Logging for audit trails
Health checks for monitoring
Graceful shutdown handling
Documentation for each tool/resource

FAQ

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI applications to external tools and data sources. It provides a unified interface so any MCP-compatible host (like Claude, Cursor, or VS Code) can use any MCP server without custom integration code.

Is MCP an Anthropic-only protocol?

No. While Anthropic created MCP, it has been donated to the Linux Foundation and is now an open standard. Any AI application can implement MCP — hosts include Cursor, VS Code, Claude Desktop, and many others from different companies.

Do I need MCP for my AI app?

Not necessarily. MCP is most valuable when you want your tools to work across multiple AI hosts without rebuilding integrations for each one. If you’re building a single-purpose app with one model provider, direct API integration may be simpler.

How do I build an MCP server?

Use the official @modelcontextprotocol/sdk package (TypeScript) or mcp package (Python). Define your tools, resources, and prompts, then connect via stdio or SSE transport. A basic server with one tool can be built in under 50 lines of code.