Model Context Protocol: Build Your First MCP Server Today

The Model Context Protocol (MCP) is an open standard that gives AI models a universal way to connect to external tools, data sources, and services. Instead of writing custom integration code for every model-tool combination, you write one MCP server and every compatible model can use it. Anthropic created MCP in late 2024, the Linux Foundation governs it now, and OpenAI, Google, and the rest of the agentic AI ecosystem have adopted it. Here's everything you need to understand, build, and deploy MCP.

MCP at a Glance

If you want the quick version before diving into 6,000 words of detail, here it is.

Now let's unpack each of these, starting with what MCP actually is and the problem that made it necessary.

What Is the Model Context Protocol?

The Model Context Protocol is an open, JSON-RPC-based protocol that standardizes how AI models discover and interact with external tools and data. Think of it as HTTP for AI integrations, a shared language that any model and any tool can speak.

You've probably heard the USB-C analogy, and it's useful up to a point: before USB-C, every device needed its own cable. MCP does the same thing for AI, but the analogy undersells it. USB-C only carries data and power. MCP carries tool definitions, data access patterns, reusable prompt templates, and even lets servers request completions from the model. It's a richer protocol than a cable metaphor suggests.

The M x N Problem MCP Solves

Without MCP, connecting M models to N tools requires M x N custom integrations. Say you support 5 LLMs (Claude, GPT-4, Gemini, Llama, Mistral) and need them to access 10 tools (GitHub, Postgres, Slack, Jira, and so on). That's 50 bespoke integration layers, each with its own authentication, error handling, and data formatting.

With MCP, each model implements the MCP client protocol once, and each tool implements an MCP server once. Now it's 5 + 10 = 15 implementations instead of 50. Add a new model? It immediately works with all 10 tools. Add a new tool? All 5 models can use it.

A Brief History of MCP

Anthropic open-sourced MCP in November 2024 alongside SDKs for Python and TypeScript plus connectors for Claude Desktop. Adoption moved fast. OpenAI added MCP support to ChatGPT in March 2025. Google followed for Gemini in April 2025. By December 2025, Anthropic donated MCP to the Linux Foundation's new Agentic AI Foundation (AAIF), co-founded with Block and OpenAI, making MCP a vendor-neutral standard with cross-industry governance.

What MCP is NOT:

• Not a model or an AI framework (it's a protocol, like HTTP)
• Not a replacement for LangChain or LlamaIndex (those are orchestration layers; MCP sits below them)
• Not limited to Anthropic or Claude (it's model-agnostic by design)
• Not the same as function calling (more on that in the comparison section)

How Does MCP Work? Architecture Deep Dive

MCP has three roles, and mixing them up is the most common beginner mistake. Let's nail the distinction.

Host, Client, and Server, What's the Difference?

Here's a concrete example: you ask Claude Desktop to check your open GitHub pull requests. Claude Desktop is the host. Its built-in MCP client opens a connection to the GitHub MCP server. The server calls the GitHub API, fetches your PRs, and returns the results to the client, which hands them to the model.

A single host can run multiple clients, each connected to a different server. That's how Claude Desktop can simultaneously access GitHub, your Postgres database, and Slack, three separate MCP servers, three separate client connections, one host.

How Messages Flow (JSON-RPC 2.0)

All MCP communication uses JSON-RPC 2.0, a lightweight request/response protocol. Here's what a tools/list exchange looks like on the wire:

// Client request: "What tools do you have?"
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

// Server response: one tool available
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

The model reads these tool definitions, decides when to call them based on the user's request, and the client sends a tools/call request back to the server with the appropriate arguments.

Connection Lifecycle

Every MCP session follows the same lifecycle:

1. Initialize, client sends capabilities, server responds with its own
2. Capability negotiation, both sides agree on supported features (tools, resources, prompts, sampling)
3. Ready, the connection is active; requests flow both directions
4. Requests/responses, tools/call, resources/read, etc.
5. Shutdown, clean disconnect

This handshake ensures forward compatibility. If a server adds a new primitive, older clients gracefully ignore it instead of crashing.

MCP Primitives: Tools, Resources, Prompts, and Sampling

MCP defines four primitives, and understanding who controls each one is the key to designing good MCP servers.

Tools (Model-Controlled)

Tools are functions the model can call. The server declares them with a name, description, and JSON Schema input definition. The model reads these definitions, and when a user's request requires it, the model decides to invoke the tool.

// Client sends tools/call request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "Berlin" }
  }
}

If you've used OpenAI function calling, tools will feel familiar, but they're standardized across every MCP-compatible model.

Resources (Application-Controlled)

Resources are read-only data endpoints. Unlike tools, the model doesn't decide to fetch a resource on its own, the host application or user explicitly attaches resources to the conversation context. Think of them like GET endpoints: postgres://mydb/users/schema, file://docs/api-reference.md.

Resources support subscriptions via resources/subscribe, so the client can be notified when data changes.

Prompts (User-Controlled)

Prompts are reusable templates that an MCP server exposes. A code_review prompt might accept a file path and generate a structured review request. The user (or host UI) triggers prompts explicitly, they're not auto-invoked by the model.

Sampling (Server-Initiated), Advanced

Here's the primitive most guides skip. Sampling lets the server ask the client to generate a completion using the LLM. This inverts the usual flow: instead of the model calling a tool, the tool calls the model.

Why? Agentic loops. Imagine an MCP server that processes support tickets. It reads the ticket (a resource), uses sampling/createMessage to ask the model for a summary, then uses that summary to route the ticket via a tool. The server orchestrates a multi-step workflow using the model's intelligence.

Sampling is gated by the host application, the user must approve it, and the host controls what the server can request. This prevents runaway loops and maintains human oversight.

Build Your First MCP Server: Python and TypeScript Side-by-Side

Enough theory. Let's build a working MCP server that exposes a get_weather tool. I'll show both Python and TypeScript so you can compare the developer experience and pick the stack that fits your project.

Python with FastMCP

FastMCP is the official high-level Python SDK. It handles all the protocol plumbing so you can focus on your tool logic.

# Install FastMCP
pip install fastmcp

# weather_server.py
from fastmcp import FastMCP

mcp = FastMCP("Weather Server")

@mcp.tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    # In production, call a real weather API here
    weather_data = {
        "Berlin": "Cloudy, 12°C",
        "Tokyo": "Sunny, 22°C",
        "New York": "Rainy, 8°C",
    }
    return weather_data.get(city, f"No data for {city}")

if __name__ == "__main__":
    mcp.run()

That's it -- 15 lines. FastMCP infers the tool's input schema from the Python type hints and docstring. No JSON Schema boilerplate.

TypeScript with the Official SDK

The TypeScript SDK (@modelcontextprotocol/sdk) is a bit more explicit but gives you full control over schema definitions.

# Install the SDK and Zod for schema validation
npm install @modelcontextprotocol/sdk zod

// weather-server.ts
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: "Weather Server",
  version: "1.0.0",
});

server.tool(
  "get_weather",
  "Get the current weather for a city",
  { city: z.string() },
  async ({ city }) => {
    const weatherData: Record<string, string> = {
      Berlin: "Cloudy, 12°C",
      Tokyo: "Sunny, 22°C",
      "New York": "Rainy, 8°C",
    };
    return {
      content: [
        { type: "text", text: weatherData[city] ?? `No data for ${city}` },
      ],
    };
  }
);

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

The TypeScript version uses Zod schemas instead of type hints, and returns structured content blocks. More verbose, but the type safety is excellent.

Connect to Claude Desktop

To wire either server into Claude Desktop, add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather-python": {
      "command": "python",
      "args": ["weather_server.py"],
      "cwd": "/path/to/your/project"
    },
    "weather-typescript": {
      "command": "npx",
      "args": ["tsx", "weather-server.ts"],
      "cwd": "/path/to/your/project"
    }
  }
}

Restart Claude Desktop, and both weather servers appear in the tool list. Ask "What's the weather in Berlin?" and the model calls your get_weather tool automatically.

Test with MCP Inspector

Before wiring your server to a host, test it in isolation with the MCP Inspector:

npx @modelcontextprotocol/inspector python weather_server.py

The Inspector opens a browser UI where you can see discovered tools, invoke them manually, and inspect the JSON-RPC messages going back and forth. It's the single best debugging tool in the MCP ecosystem, use it early and often.

MCP Transports: stdio for Dev, Streamable HTTP for Production

MCP messages need a way to travel between client and server. That's the transport layer, and picking the right one matters.

stdio works by spawning the MCP server as a subprocess and communicating over stdin/stdout. It's what you used in the tutorial above, no ports, no TLS, no auth needed. Perfect for development and single-user local tools.

Streamable HTTP is the production transport, added in the 2025 spec update. Clients send standard HTTP POST requests to the server. The server can respond synchronously or open an SSE stream for longer operations. It's stateless-friendly, works behind load balancers, and supports standard HTTP authentication.

If you see older tutorials mentioning "HTTP+SSE" as two separate transports (one for sending, one for receiving), that's the deprecated approach. Streamable HTTP consolidates both into a single, cleaner mechanism.

The decision is straightforward: use stdio when developing locally, switch to streamable-http when deploying for others.

// Switching from stdio to Streamable HTTP in TypeScript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const transport = new StreamableHTTPServerTransport({ port: 3001 });
await server.connect(transport);

MCP vs Function Calling vs REST APIs, When to Use Each

This is the question that comes up in every MCP discussion, so let's settle it with a direct comparison.

When Function Calling Is Enough

If you have fewer than 5 tools and use one model, function calling is simpler. You define your tool schemas inline with each API call, the model returns the function name and arguments, and you execute them in your application code. No server to run, no protocol to learn. For a chatbot that checks order status and looks up FAQs, function calling is perfectly fine.

When MCP Becomes Worth It

MCP earns its complexity when:

• You support multiple LLMs and don't want to rewrite tool definitions for each provider
• You need tool discovery, the model can query what's available instead of you hardcoding schemas
• You want resources and prompts, not just tool calls
• You're building AI agents that coordinate autonomously and need a standardized integration layer
• Your team is growing and different engineers build different tools, MCP lets them work independently

Verdict: MCP wins when you need standardized, multi-model tool access. Function calling wins for simple, single-model use cases. REST APIs remain the right choice for traditional service-to-service communication that doesn't involve an LLM.

The MCP Ecosystem in 2026: Who Supports It and What's Available

MCP went from an Anthropic side project to an industry standard in under 18 months. Here's where things stand.

Which LLMs Support MCP?

Popular MCP Servers Worth Knowing

The Linux Foundation's AAIF announcement cited 10,000+ active servers and 97 million monthly SDK downloads at the time of MCP's donation in December 2025. The ecosystem is no longer experimental, it's production-grade.

MCP Apps is a new primitive introduced in January 2026. It lets servers provide interactive UI components that render inside the host application. Still early, but it signals MCP's evolution from a data protocol to a full agent-application framework. Worth watching.

Governance: From Anthropic to the Linux Foundation

MCP is governed by the Agentic AI Foundation (AAIF) under the Linux Foundation, co-founded by Anthropic, Block, and OpenAI. This matters for enterprise adoption: MCP isn't tied to one vendor's roadmap. The 2026 roadmap priorities are transport evolution, agent-to-agent communication (a new "Tasks" primitive), governance maturation, and enterprise readiness.

For teams building production AI systems, frameworks like an autonomous AI agent framework like OpenClaw already integrate with MCP servers to give agents real-world capabilities.

MCP Security: OAuth 2.1, Threats, and a Practical Checklist

Security is where the MCP ecosystem has the most ground to cover. And the numbers paint a stark picture.

The 88% Problem: Why Most MCP Servers Are Insecure

Astrix Security analyzed 5,200+ open-source MCP server implementations and found that 88% require credentials of some kind, but 53% rely on insecure long-lived static secrets like API keys and personal access tokens hardcoded in config files. Only 8.5% implement OAuth.

That means the overwhelming majority of MCP servers in the wild are using the authentication equivalent of taping your house key to the front door.

OAuth 2.1 for MCP Servers

The MCP specification requires OAuth 2.1 for all HTTP-based servers as of the June 2025 update. The flow works like this: the MCP client initiates an OAuth 2.1 authorization flow with the server, obtains a scoped access token, and includes it with every subsequent request. PKCE (Proof Key for Code Exchange) is required for all clients, no exceptions.

If you're building an MCP server that runs over Streamable HTTP, OAuth 2.1 isn't optional. It's spec-mandated.

Threat Model: What Can Go Wrong

Four threats deserve attention in any MCP deployment:

• Prompt injection via tools, A malicious or compromised data source returns content designed to manipulate the model. If a tool fetches a webpage and that page contains hidden instructions, the model might execute them.
• Confused deputy attack, The model invokes a tool with broader permissions than the user intended. If the MCP server has admin access to a database, the model could theoretically drop a table.
• Token concentration risk, An MCP server that holds API keys for GitHub, Slack, and your production database is a single high-value target. Compromise one server, compromise everything it connects to.
• Insecure transport, Running an HTTP MCP server without TLS exposes every request, including OAuth tokens and sensitive data, in plaintext.

Security Checklist for Production MCP

1. Implement OAuth 2.1 for any server exposed over HTTP. No static API keys in config files.
2. Apply least-privilege scoping. If your tool only reads data, the server's credentials should be read-only. Don't give a reporting tool write access.
3. Isolate credentials. Each MCP server should have its own scoped tokens. Don't share a single "god token" across servers.
4. Enforce TLS everywhere. Streamable HTTP without HTTPS is an automatic no-go for production.
5. Validate and sanitize tool outputs. Treat data returned by tools the same way you'd treat user input, don't trust it blindly.
6. Rate-limit tool invocations. A runaway agent loop calling a tool thousands of times can exhaust API quotas or cause unintended side effects.
7. Audit and log every tool call. Include request IDs, timestamps, the calling model, and the tool arguments. You need this for debugging and for security incident response.

Debugging MCP: Inspector, Logging, and Common Errors

You will hit errors. Every developer does. Here's how to fix them fast.

MCP Inspector is the official debugging tool and your first line of defense. It connects to any MCP server, discovers its tools/resources/prompts, and lets you invoke them manually while showing the raw JSON-RPC traffic.

# Launch Inspector against your Python server
npx @modelcontextprotocol/inspector python weather_server.py

# Or against a TypeScript server
npx @modelcontextprotocol/inspector npx tsx weather-server.ts

The Inspector opens a browser-based UI with tabs for Tools, Resources, Prompts, and a notifications pane. You can call any tool with custom arguments and see exactly what JSON goes over the wire. Use it before connecting to a host application, it's much easier to debug the server in isolation.

Common Errors and Fixes

• "Server not found" in Claude Desktop, Almost always a path issue in claude_desktop_config.json. Double-check that command resolves to a real binary and cwd points to the correct directory. On macOS, use absolute paths.
• Tool schema validation failures, If the model sends arguments that don't match the tool's inputSchema, the server rejects the call. Check that your schema types match what the model expects. Zod (TypeScript) and type hints (Python) catch most of these at definition time.
• Transport connection drops, For stdio, this usually means the server process crashed. Check stderr output. For Streamable HTTP, verify timeout settings, long-running tools may exceed default HTTP timeouts.
• "Permission denied" or 401 errors, OAuth scope too narrow. The server is rejecting the token because it doesn't have the required permissions. Widen the scope, but only as much as the tool actually needs.

Logging Best Practices

Structure your logs with request IDs so you can trace a single user request across the MCP client, server, and any downstream APIs. Log every tools/call invocation with the tool name, arguments, response time, and result status. In production, ship these logs to an observability platform, when something goes wrong at 3 AM, you'll be glad you did.

How Techsy Builds with MCP

We've been integrating MCP into client projects since early 2025, and the pattern we see most often is this: a team has an AI feature that works with one model and a handful of tools, but they're planning to scale, more models, more data sources, more agent capabilities. That's the inflection point where MCP starts paying off.

Our approach follows three steps:

1. Assess fit. Not every project needs MCP. If you're calling two tools from a single model, function calling is simpler and we'll tell you that. MCP makes sense when you're connecting 3+ data sources, supporting multiple models, or building agent workflows where tools need to be discoverable.
2. Build and test servers in isolation. We develop custom MCP servers for each data source, internal databases, SaaS APIs, proprietary services, and validate them with MCP Inspector before connecting to any host.
3. Deploy with Streamable HTTP and OAuth 2.1. For production, we run MCP servers as containerized services behind TLS, with scoped OAuth tokens and structured logging from day one. No static secrets.

The most common integrations we build: connecting AI assistants to internal Postgres databases, building custom MCP servers for client SaaS platforms, and migrating teams from scattered function-calling setups to a standardized MCP architecture.

Building AI-powered tools that need to connect to your infrastructure? We help teams architect and implement MCP integrations. Get a free consultation

Frequently Asked Questions About MCP

What is the Model Context Protocol (MCP)?

MCP is an open standard, originally created by Anthropic and now governed by the Linux Foundation, that defines how AI models connect to external tools, data sources, and services. It standardizes the integration layer so one MCP server works with any compatible model, like a universal plug for AI.

How does MCP work?

MCP uses a three-part architecture: a host application (like Claude Desktop or Cursor), an MCP client inside the host that manages connections, and MCP servers that expose tools and data. All communication uses JSON-RPC 2.0 messages over either stdio (local) or Streamable HTTP (remote).

What is MCP used for?

Common use cases include connecting AI assistants to databases (Postgres, MySQL), integrating with code platforms (GitHub, GitLab), accessing SaaS tools (Slack, Notion, Google Drive), and building autonomous AI agents that need to interact with real-world services.

Is MCP the same as function calling?

No. Function calling is model-specific (OpenAI's format differs from Anthropic's) and per-request, you send tool schemas with every API call. MCP is a standardized protocol that works across models, supports tool discovery, and includes resources and prompts beyond just function execution.

What are MCP servers?

MCP servers are programs that expose tools, resources, and prompts to AI models via the MCP protocol. They wrap external APIs and data sources in a standardized interface. Examples include the GitHub MCP server (for PR and issue management) and the Postgres MCP server (for database queries).

How do I build an MCP server?

Use Python with FastMCP (pip install fastmcp) or TypeScript with the official SDK (npm install @modelcontextprotocol/sdk). Define your tools as decorated functions (Python) or registered handlers (TypeScript), then run the server. See the tutorial section above for complete working code, or follow our step-by-step guide to building an MCP server from scratch for a full walkthrough.

Is MCP secure?

The protocol itself supports OAuth 2.1 for authentication and scoped permissions. However, Astrix Security research found that 88% of existing MCP server implementations rely on static secrets rather than OAuth. The protocol is secure by design, but most real-world deployments haven't caught up yet.

What LLMs support MCP?

Claude has native MCP support since its creation in November 2024. ChatGPT added support in March 2025, and Gemini followed in April 2025. Open-source models can use MCP through adapters in LangChain and LlamaIndex.

What is the difference between MCP and a REST API?

REST APIs are designed for general service-to-service communication. MCP is designed specifically for AI model interaction, it includes tool discovery, schema negotiation, resource access, and prompt templates that REST doesn't have. You wouldn't replace your REST APIs with MCP; they serve different layers.

Who maintains MCP now?

The Linux Foundation's Agentic AI Foundation (AAIF), formed in December 2025, governs MCP. It was co-founded by Anthropic, Block, and OpenAI. This vendor-neutral governance is a key reason enterprises are adopting MCP.

What is Streamable HTTP in MCP?

Streamable HTTP is the production transport mechanism added in the 2025 MCP spec update. It replaces the older HTTP+SSE transport with a cleaner design: clients send HTTP POST requests, and servers can respond synchronously or via SSE streaming. It works behind load balancers and supports standard HTTP authentication.

How many MCP servers exist?

The Linux Foundation cited 10,000+ active servers and 97 million monthly SDK downloads when MCP was donated to AAIF in December 2025. The ecosystem spans databases, code tools, SaaS integrations, search engines, and cloud infrastructure providers.

Conclusion

MCP has gone from Anthropic's open-source experiment to the industry-standard protocol for connecting AI models to tools in just over a year. Here's what matters:

• MCP solves the M x N problem, one server works with every compatible model, one client works with every server
• You can build a working MCP server in under 50 lines of Python (FastMCP) or TypeScript
• Use stdio for development, Streamable HTTP for production, the transport choice is straightforward
• Secure your servers with OAuth 2.1 -- 88% of current implementations don't, and that's a real risk
• The ecosystem is production-ready -- 10,000+ servers, all major LLMs, vendor-neutral governance under the Linux Foundation

Looking ahead, the 2026 roadmap focuses on agent-to-agent communication via a new Tasks primitive, enhanced enterprise security, and MCP Apps for interactive server-driven UI. MCP isn't just a protocol for tool access anymore, it's becoming the infrastructure layer for agentic AI.

Start with the tutorial code above, test it in MCP Inspector, and connect it to Claude Desktop. You'll have a working MCP integration in under an hour.

Sources

• MCP Specification (2025-11-25)
• MCP Authorization Specification
• MCP Transports Specification
• MCP Inspector Documentation
• Introducing the Model Context Protocol, Anthropic
• Donating MCP to the Linux Foundation, Anthropic
• Linux Foundation AAIF Announcement
• Google Cloud MCP Support
• FastMCP Python SDK
• MCP TypeScript SDK
• Astrix Security: State of MCP Server Security 2025
• MCP 2026 Roadmap