Hirak

Posted on Jun 24 • Originally published at stackwrite.com

How MCP Servers Work — The Complete Developer Guide (2026)

#mcp #ai #guide

MCP is the most important protocol in AI tooling right now and most developers still don't understand how it works. This guide fixes that.

What Is MCP?

MCP stands for Model Context Protocol. It's an open standard created by Anthropic that lets AI tools — Claude Code, Cursor, Windsurf, and others — connect to external services through a standardized interface.

Think of it like USB for AI. Before USB, every device had its own connector. Before MCP, every AI integration was custom-built. MCP gives AI tools a universal way to talk to GitHub, databases, browsers, APIs, and anything else you can build a server for.

Why Does MCP Exist?

AI coding tools hit a ceiling fast: they can only work with what's in their context window. They can't check your GitHub issues. They can't query your database. They can't browse the web.

MCP removes that ceiling. An MCP server exposes tools (actions the AI can take) and resources (data the AI can read). The AI calls these tools the same way it calls its built-in capabilities — naturally, as part of the conversation.

Without MCP, you copy-paste. With MCP, you just ask.

How the Protocol Works

The architecture has three components:

[AI Tool (Host)] <---> [MCP Client] <---> [MCP Server] <---> [External Service]

Host — The AI application (Claude Code, Cursor, etc.)

Client — Built into the host. Manages the connection to MCP servers. Handles capability negotiation and message routing.

Server — A lightweight program that exposes tools and resources. Runs locally or remotely.

The Handshake

When Claude Code starts, it reads your MCP configuration and launches each server as a subprocess. Here's what happens:

Initialize — Client sends initialize request with protocol version and capabilities
Negotiate — Server responds with its capabilities (which tools it exposes, what resources it has)
Ready — Client sends initialized notification. The connection is live.

From here, the AI can call any tool the server exposes.

Message Format

MCP uses JSON-RPC 2.0 over stdio (standard input/output). A tool call looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_issue",
    "arguments": {
      "repo": "owner/repo",
      "title": "Fix login redirect bug",
      "body": "Users get a 404 after OAuth callback"
    }
  }
}

The server processes the request, talks to GitHub's API, and returns the result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Created issue #42" }]
  }
}

The AI sees the result and continues the conversation naturally. "I created issue #42 for the login redirect bug."

The Three Primitives

Every MCP server exposes some combination of these:

1. Tools (Actions)

Things the AI can do. Create a PR, run a query, send a message, take a screenshot. Tools are the most common primitive.

server.tool("query_database", {
  description: "Run a read-only SQL query",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "SQL query to execute" }
    },
    required: ["query"]
  }
}, async ({ query }) => {
  const result = await db.query(query);
  return { content: [{ type: "text", text: JSON.stringify(result.rows) }] };
});

2. Resources (Data)

Things the AI can read. File contents, database schemas, API documentation, configuration. Resources are identified by URIs.

server.resource("schema://main", {
  name: "Database Schema",
  description: "Current database table definitions",
  mimeType: "text/plain"
}, async () => {
  const schema = await db.query("SELECT * FROM information_schema.tables");
  return { contents: [{ text: formatSchema(schema), uri: "schema://main" }] };
});

3. Prompts (Templates)

Reusable prompt templates the AI can invoke. Less commonly used, but useful for standardizing complex workflows like code reviews or architecture analyses.

How to Build an MCP Server

It takes about 30 minutes to build a basic MCP server. Here's a minimal example in TypeScript:

npm init -y
npm install @modelcontextprotocol/sdk

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

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

// Add a tool
server.tool("get_weather", {
  description: "Get current weather for a city",
  inputSchema: {
    type: "object",
    properties: {
      city: { type: "string" }
    },
    required: ["city"]
  }
}, async ({ city }) => {
  const weather = await fetch(`https://wttr.in/${city}?format=j1`).then(r => r.json());
  const temp = weather.current_condition[0].temp_C;
  return { content: [{ type: "text", text: `${city}: ${temp}°C` }] };
});

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

Register It With Claude Code

Add to your .mcp.json or Claude Code settings:

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

Restart Claude Code. Now you can ask "What's the weather in Toronto?" and it calls your server.

Top Use Cases in 2026

Based on what developers actually use daily:

GitHub — PRs, issues, code search (51 tools, most popular MCP server by far)
Database access — Query Postgres, MySQL, SQLite conversationally
Browser automation — Playwright-based testing and scraping
Build tools — XcodeBuildMCP for iOS, Gradle for Android
Monitoring — Sentry crash reports, Datadog metrics
Search — Brave Search for real-time web access
Memory — Persistent context across sessions

For the full list of recommended servers, see The 10 Best MCP Servers Every Developer Needs.

Common Mistakes

Running too many servers. Each server consumes memory and adds latency to startup. Start with 2-3. Add more only when you have a specific use case.

Not reading the tool descriptions. When the AI makes a bad tool call, it's usually because the tool's description is vague. Write descriptions like documentation — clear, specific, with examples.

Ignoring security. MCP servers can read files, execute queries, and call APIs. Scope permissions tightly. Use read-only database connections. Never expose admin APIs.

Building what already exists. Before writing a custom server, check the MCP server registry. There are 100+ community servers covering most common use cases.

MCP vs Function Calling vs Plugins

Feature	MCP	Function Calling	ChatGPT Plugins
Standard	Open protocol	Vendor-specific	Deprecated
Runtime	Local process	Cloud API	Cloud API
Latency	Low (local)	Higher (API round-trip)	Highest
Security	You control everything	Provider-mediated	Provider-mediated
Ecosystem	100+ servers, growing	N/A	Dead

MCP won because it's open, local, fast, and developer-controlled. Function calling still matters for cloud-hosted AI, but for coding tools, MCP is the standard.

What's Next for MCP

The protocol is evolving fast. Upcoming features in the spec:

Streamable HTTP transport — Run MCP servers remotely over HTTP instead of just stdio
OAuth integration — Standardized auth for remote servers
Elicitation — Servers can ask the user questions mid-workflow

The trajectory is clear: MCP is becoming the universal integration layer for AI tools. Learning it now pays compounding dividends.

DEV Community