Solo UnicornThe Complete Guide to Building an MCP Server
The Complete Guide to Building an MCP Server
Introduction
MCP (Model Context Protocol) is an open protocol that Anthropic released in November 2024. By March 2026, the Python and TypeScript SDKs have surpassed 97 million monthly downloads combined. It solves a core problem: giving AI models a standardized way to connect to external tools and data. I've built 4 production-grade MCP Servers, and this article walks through the entire process — from environment setup to tool definition to security hardening — leaving nothing out.
The Problem
Before MCP, every AI application needed a bespoke integration with every external tool. 3 AI applications + 5 tools = 15 integration codebases. MCP turns this M x N problem into M + N: each tool exposes one MCP Server, each AI application implements one MCP Client, and they communicate through a standard protocol.
In December 2025, Anthropic donated MCP to the Agentic AI Foundation (AAIF) under the Linux Foundation. OpenAI, Google, Microsoft, and AWS all joined. This means MCP is no longer a single-vendor protocol — it's an industry standard.
If you're doing agent development, you can't afford not to learn MCP at this point.
Core Architecture
The Three Fundamental Concepts of MCP
MCP Client (AI Application) <-> MCP Server (Tool Provider)
|
Standardized Protocol Layer
+-------------------+
| Tools | <- Functions the agent can call
| Resources | <- Data the agent can read
| Prompts | <- Predefined prompt templates
+-------------------+
Tools: Functions the agent can call, with input parameters and output results. Similar to function calling, but exposed through a standard protocol.
Resources: Data sources the agent can read. For example, database tables, file contents, or API response data. Read-only — the agent cannot modify them.
Prompts: Predefined prompt templates. For example, a "analyze this report" prompt where the server provides a standardized analysis workflow.
Transport Methods
MCP supports two transport methods:
| Transport | Use Case | Characteristics |
|---|---|---|
| stdio | Local tools | Communicates via standard input/output, simple and direct |
| HTTP + SSE | Remote services | Uses HTTP requests + Server-Sent Events, supports network deployment |
stdio is sufficient for local development. Production deployments typically use HTTP + SSE (the November 2025 spec also supports Streamable HTTP).
Implementation Details
Step 1: Building a Python MCP Server
Using the official Python SDK:
# Install the MCP Python SDK
pip install mcp
A minimal MCP Server requires just a few dozen lines of code:
from mcp.server.fastmcp import FastMCP
import httpx
import json
# Create an MCP Server instance
mcp = FastMCP(
name="company-data-server",
version="1.0.0"
)
# Define a Tool: look up customer information
@mcp.tool()
async def get_customer(customer_id: str) -> str:
"""Look up detailed customer information by customer ID.
Args:
customer_id: The customer's unique identifier
"""
# Actually query the database
async with httpx.AsyncClient() as client:
resp = await client.get(
f"https://api.internal.com/customers/{customer_id}",
headers={"Authorization": f"Bearer {API_TOKEN}"}
)
data = resp.json()
return json.dumps({
"name": data["name"],
"email": data["email"],
"plan": data["subscription_plan"],
"mrr": data["monthly_revenue"]
}, ensure_ascii=False)
# Define a Tool: create a ticket
@mcp.tool()
async def create_ticket(
title: str,
description: str,
priority: str = "medium"
) -> str:
"""Create a new ticket in the ticketing system.
Args:
title: Ticket title
description: Detailed problem description
priority: Priority level, one of low/medium/high
"""
if priority not in ("low", "medium", "high"):
return json.dumps({"error": "priority must be one of low/medium/high"})
async with httpx.AsyncClient() as client:
resp = await client.post(
"https://api.internal.com/tickets",
headers={"Authorization": f"Bearer {API_TOKEN}"},
json={
"title": title,
"description": description,
"priority": priority
}
)
ticket = resp.json()
return json.dumps({
"ticket_id": ticket["id"],
"status": "created",
"url": f"https://tickets.internal.com/{ticket['id']}"
})
# Define a Resource: product catalog
@mcp.resource("products://catalog")
async def get_product_catalog() -> str:
"""Retrieve the complete product catalog data"""
async with httpx.AsyncClient() as client:
resp = await client.get("https://api.internal.com/products")
return resp.text
# Define a Prompt: customer analysis template
@mcp.prompt()
async def analyze_customer(customer_id: str) -> str:
"""Generate a standard prompt for customer analysis"""
return f"""Please analyze the data for customer {customer_id}, including:
1. Current subscription status and MRR
2. Usage trends over the past 30 days
3. Churn risk assessment
4. Recommended follow-up strategy
Use the get_customer tool to fetch customer data before performing the analysis."""
if __name__ == "__main__":
mcp.run() # Uses stdio transport by default
Step 2: TypeScript Version
If your team uses TypeScript:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// Create the Server
const server = new McpServer({
name: "company-data-server",
version: "1.0.0",
});
// Define a Tool
server.tool(
"get_customer",
"Look up detailed customer information by customer ID",
{
customer_id: z.string().describe("The customer's unique identifier"),
},
async ({ customer_id }) => {
// Query logic
const resp = await fetch(
`https://api.internal.com/customers/${customer_id}`,
{ headers: { Authorization: `Bearer ${process.env.API_TOKEN}` } }
);
const data = await resp.json();
return {
content: [
{
type: "text",
text: JSON.stringify({
name: data.name,
email: data.email,
plan: data.subscription_plan,
}),
},
],
};
}
);
// Start the Server (stdio transport)
const transport = new StdioServerTransport();
await server.connect(transport);
Step 3: Configuring in Claude Desktop
Once your MCP Server is built, you need to configure it on the client side. Using Claude Desktop as an example:
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"company-data": {
"command": "python",
"args": ["/path/to/company_data_server.py"],
"env": {
"API_TOKEN": "your-api-token-here"
}
}
}
}
In Claude Code:
// .claude/settings.json
{
"mcpServers": {
"company-data": {
"command": "python",
"args": ["/path/to/company_data_server.py"],
"env": {
"API_TOKEN": "your-api-token-here"
}
}
}
}
Step 4: Security Hardening
Production MCP Servers must address security:
from functools import wraps
import time
import logging
logger = logging.getLogger("mcp-server")
# Rate limiter decorator
class RateLimiter:
def __init__(self, max_calls: int, window_seconds: int):
self.max_calls = max_calls
self.window = window_seconds
self.calls: list[float] = []
def check(self) -> bool:
now = time.time()
self.calls = [t for t in self.calls if now - t < self.window]
if len(self.calls) >= self.max_calls:
return False
self.calls.append(now)
return True
rate_limiter = RateLimiter(max_calls=100, window_seconds=60)
# Input validation + logging + rate limiting
@mcp.tool()
async def get_customer_secure(customer_id: str) -> str:
"""Look up customer information (with security checks)"""
# Rate limiting
if not rate_limiter.check():
return json.dumps({"error": "Request rate too high, please try again later"})
# Input validation (prevent injection)
if not customer_id.isalnum() or len(customer_id) > 20:
return json.dumps({"error": "Invalid customer ID format"})
# Audit logging
logger.info(f"Tool called: get_customer, id={customer_id}")
# Execute the query
try:
result = await _query_customer(customer_id)
# Data sanitization (strip sensitive fields)
result.pop("ssn", None)
result.pop("credit_card", None)
return json.dumps(result, ensure_ascii=False)
except Exception as e:
logger.error(f"Query failed: {e}")
return json.dumps({"error": "Query failed, please try again"})
Security checklist:
- Input validation: Check format and length for all parameters
- Rate limiting: Prevent runaway agents from making excessive calls
- Data sanitization: Strip sensitive fields before returning results
- Audit logging: Record the parameters and results of every tool call
- Least privilege: The API token used by the MCP Server should only have the permissions it needs
Real-World Results
Production Data
An MCP Server I built for a SaaS product has been running for 3 months:
| Metric | Value |
|---|---|
| Registered Tools | 12 |
| Registered Resources | 8 |
| Daily average invocations | 2,300 |
| Average response latency | 180ms (local stdio) / 320ms (HTTP) |
| Error rate | 0.3% |
| Rejected due to rate limiting | 1.2% |
Pitfalls I Hit
Pitfall 1: Tool descriptions determine invocation quality. An MCP Tool's description isn't just for humans — the LLM uses it to decide when and how to call the tool. Initially my descriptions were vague ("get data"), which caused Claude to frequently call the wrong tool. After switching to precise descriptions ("Look up a customer's subscription plan, monthly revenue, and contact information by customer ID"), invocation accuracy jumped from 78% to 96%.
Pitfall 2: stderr gets swallowed. In stdio transport mode, Python's print output goes to stdout, which interferes with MCP protocol communication. All logging must go to stderr or be written to files — you cannot use print. This one took me two hours to track down.
Pitfall 3: Large data payloads. One time a Resource returned the full product catalog (50MB JSON), which blew up Claude's context window. The fix: paginate large Resources, or convert them to Tools that support conditional queries.
When to Use MCP
Good fit for MCP:
- You have multiple AI applications that need to access the same set of tools
- You want your tools to work with multiple LLMs (Claude, GPT, Gemini)
- You need a standardized tool discovery and description mechanism
Not a good fit for MCP:
- You have just one AI application and one or two tools — use the Tool Use API directly, it's simpler
- You need ultra-low latency (< 50ms) — the MCP protocol layer adds overhead
- Your tool logic changes frequently — every Tool definition change requires a server restart
Takeaways
Three core takeaways:
-
MCP is the standard answer for agent tool integration — whether you're using Claude, GPT, or Gemini, a single MCP Server can serve all models. With AAIF driving adoption, agent frameworks that don't support MCP will become increasingly marginalized in 2026.
-
Tool description quality matters more than tool implementation quality — the LLM decides whether and how to call a tool based on its description. Write descriptions like user documentation: clearly state the inputs, outputs, and applicable scenarios.
-
Security hardening is not optional — an MCP Server is essentially an API endpoint exposed to AI. Rate limiting, input validation, data sanitization, and audit logging are all non-negotiable.
If you haven't built an MCP Server yet, I'd suggest starting with the smallest possible server — one with a single tool — getting it working with Claude Desktop, then gradually adding Tools and Resources. The whole process takes under an hour.
Have questions about MCP? Or already built your own MCP Server? I'd love to hear about it.