How to build an MCP server and add it to Claude Code

What you're building

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external systems. An MCP server exposes:

• Tools: functions the model can call (e.g. get_order, create_ticket).
• Resources: data the client can read (files, records, documents).
• Prompts: reusable prompt templates.

Servers run locally over stdio (great for developer tools) or remotely over Streamable HTTP (for teams and customers, usually with OAuth).

Option A: Python with FastMCP

# install: pip install "mcp[cli]"   (or: uv add "mcp[cli]")
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders")

ORDERS = {"1001": {"status": "shipped", "eta": "2026-11-18"}}

@mcp.tool()
def get_order(order_id: str) -> dict:
    """Look up an order by its ID and return status and ETA."""
    order = ORDERS.get(order_id)
    if not order:
        return {"error": f"No order {order_id}. Ask the user to check the ID."}
    return order

if __name__ == "__main__":
    mcp.run()  # stdio by default

Option B: TypeScript with the official SDK

// npm i @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: "orders", version: "1.0.0" });

server.registerTool(
  "get_order",
  {
    title: "Get order",
    description: "Look up an order by its ID and return status and ETA.",
    inputSchema: { order_id: z.string() },
  },
  async ({ order_id }) => ({
    content: [{ type: "text", text: JSON.stringify({ order_id, status: "shipped" }) }],
  })
);

await server.connect(new StdioServerTransport());

Test it with MCP Inspector

npx @modelcontextprotocol/inspector python server.py
# or
npx @modelcontextprotocol/inspector node build/index.js

The Inspector lists your tools and lets you call them by hand, which is the fastest way to debug schemas and errors.

Add your MCP server to Claude Code

# local stdio server
claude mcp add orders -- python /path/to/server.py

# remote HTTP server
claude mcp add --transport http orders https://mcp.example.com/mcp

# share with your team via a checked-in .mcp.json
claude mcp add --scope project orders -- python server.py

# check what's connected
claude mcp list

Inside a session, /mcp shows server status and handles authentication for remote servers. Claude Desktop and other clients such as Cursor and VS Code take similar config pointing to the same command or URL.

Designing tools models use well

1. Few, clear tools beat many vague ones. Name them by intent (search_customers, not query).
2. Write descriptions for the model: when to use the tool, what it returns, and its limits.
3. Tight input schemas with enums and formats, so the model can't pass nonsense.
4. Helpful errors that tell the model what to do next, not just a stack trace.
5. Return only what's needed, and paginate large results to save context.
6. Least privilege: read-only by default, with explicit tools for writes and confirmation for destructive actions.
7. Treat tool output as untrusted if it contains user or web content (prompt injection).