MCP Server Builder's Quick Reference

What MCP is, in one page

The Model Context Protocol is a JSON-RPC 2.0 wire protocol that lets a language-model client (Claude Desktop, Claude Code, an agent runtime) talk to an external server that exposes tools, resources, and prompts. The server runs in a separate process. The client launches it or connects to it. They speak JSON over a transport: stdio, Streamable HTTP, or SSE.

MCP is not an LLM API. It does not call models. It is the bridge between a model-facing client and the outside world. A server might wrap a database, a shell, a file system, a web search, a hardware device, or a SaaS API. The client decides which servers to load, and the model decides which tools to call.

The three primitives

If you only build one primitive, build tools. Resources and prompts are nice; tools are why MCP exists.

The handshake

1. Client launches the server (stdio) or opens a connection (HTTP).
2. Client sends initialize with its protocol version and capabilities.
3. Server replies with its protocol version, capabilities, and server info.
4. Client sends notifications/initialized. Session is now live.
5. Client calls tools/list, resources/list, prompts/list to enumerate.
6. From there, normal request/response (tools/call, resources/read, etc.).

Pick a language: Python or TypeScript

Both SDKs are first-party. Pick by where your existing code lives.

Most servers published on the public registries are Python. Most servers shipped inside paid products are TypeScript (smaller image, faster cold-start). For a first server, Python.

Python: FastMCP in 30 lines

mcp[cli] is the official Python SDK. FastMCP is the high-level API on top.

# pyproject: dependencies = ["mcp[cli]>=1.2"]
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_forecast(city: str, days: int = 1) -> str:
    """Return a plain-text weather forecast for a city.

    Args:
        city: City name in English.
        days: 1-7. Defaults to 1.
    """
    return fetch_forecast(city, days)   # your code

@mcp.resource("weather://{city}/current")
def current(city: str) -> str:
    return fetch_current(city)

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

Three things to notice. First, the docstring becomes the tool description the model sees. Write it for the model, not for a human reader. Second, type hints become the JSON Schema. int = 1 means optional with default. Use Literal['a','b'] for enums. Third, mcp.run() blocks on stdio. For HTTP, see section 7.

Naming

• Server name: lowercase, hyphen-separated, matches the package name. e.g. weather, github-search, polymarket-data.
• Tool names: snake_case verb_object. e.g. get_forecast, create_issue, place_order. The model picks tools by name; pick names that read like an English imperative.
• Resource URIs: scheme://path. The scheme is your namespace. Be consistent. weather://city/current, github://repo/issues/123.

Python: tool I/O and errors

FastMCP marshals return values into MCP content blocks. Three rules.

• Return a str for plain text. The simplest case.
• Return a dict or list and FastMCP serializes as JSON inside a text block. The model reads it fine; this is the default for structured data.
• Return mcp.types.ImageContent(data=..., mimeType=...) for images. The data is base64. The model can see it if the client supports image content.

Errors

Raise. FastMCP catches and converts to an MCP error response. The model sees the message; show it something actionable.

@mcp.tool()
def transfer(amount: float, to: str) -> str:
    if amount <= 0:
        raise ValueError("amount must be > 0")
    if amount > balance():
        raise ValueError(
            f"insufficient balance: have {balance()},"
            f" need {amount}"
        )
    return do_transfer(amount, to)

Good error text reads as an instruction to the caller: what went wrong, what would fix it. Bad error text is a stack trace or "internal error". The model can recover from the first; the second wastes a turn.

Python: Context, progress, logs

Inject an mcp.server.fastmcp.Context parameter into any tool to get access to logging, progress reporting, and the active session.

from mcp.server.fastmcp import FastMCP, Context

@mcp.tool()
async def crawl(url: str, depth: int, ctx: Context) -> str:
    pages = enumerate_pages(url, depth)
    for i, page in enumerate(pages):
        await ctx.report_progress(i, len(pages))
        ctx.info(f"fetched {page.url}")
    return summarize(pages)

report_progress is shown by graphical clients (Claude Desktop shows a bar). ctx.info / ctx.warning / ctx.error go to the client's log surface; the model does not see them. Use them for post-mortem debugging, not for routing model behavior.

TypeScript: minimal server

@modelcontextprotocol/sdk is the official TypeScript SDK. The API mirrors the Python one but is more explicit (no decorators).

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", version: "0.1.0",
});

server.tool(
  "get_forecast",
  "Return a forecast for a city.",
  {
    city: z.string(),
    days: z.number().int().min(1).max(7).default(1),
  },
  async ({ city, days }) => {
    const text = await fetchForecast(city, days);
    return { content: [{ type: "text", text }] };
  },
);

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

Use Zod for input schemas. The SDK converts Zod to JSON Schema for the protocol. Return shape is { content: [...] } with one or more content blocks. Each block has a type (text, image, resource).

Package layout

• package.json bin field points at the entry file (with #!/usr/bin/env node). Users invoke via npx your-server.
• Ship as ESM. CommonJS works but the modern templates assume ESM.
• Mark the server's stdout as protocol-only: never console.log to stdout. Use console.error for diagnostics so the client doesn't choke parsing JSON.

Transports

stdio (default for local servers)

The client launches the server as a subprocess. Requests go in on stdin, responses on stdout, diagnostics on stderr. Zero network. Works everywhere. Default for Claude Desktop and Claude Code server configs.

Streamable HTTP (current standard for remote)

One POST endpoint. Client sends JSON-RPC requests; server streams responses as Server-Sent Events. Replaces the older SSE transport. Use for any server that runs out-of-process, on a different machine, or behind a load balancer.

# Python (FastMCP) -- HTTP server on :8000
mcp.run(
    transport="streamable-http",
    host="0.0.0.0",
    port=8000,
)

SSE (deprecated, but still seen)

Older two-endpoint design: GET /sse for the event stream, POST /messages for requests. New servers should not implement SSE. Existing servers should migrate when the client matrix permits.

Picking one

Authentication

Stdio servers do not authenticate; the OS process boundary is the trust boundary. The user trusts the client; the client trusts the server it launches. If a stdio server needs an API key, read it from an environment variable the client injects.

HTTP servers: pick one

Secret handling

• Never log the token. The SDKs do not log request bodies by default; if you add middleware, redact Authorization headers.
• Rotate. A token that lives forever is a token that leaks forever.
• Scope. If the upstream API supports scoped tokens, mint the narrowest one the server needs and document the scopes in the README.

Tool descriptions: what the model actually reads

The model decides whether to call your tool based on the tool name, description, and parameter schema. Treat the description as the tool's marketing copy aimed at the model. Three rules.

1. Lead with WHEN to use it, not what it does. "Use this to look up the current price of a stock. Returns the latest trade price in USD." beats "Fetches financial data."
2. Name the inputs in plain language inside the description, even though they are also in the schema. The model is more reliable about parameter shapes when both signals agree.
3. Mention what the tool does NOT do, if it is easy to confuse with another tool. "This is delete_file, not move_file — the file is gone after this call."

Test by reading the description aloud and asking: if I knew nothing else, would I know when to call this? If you have to clarify out loud, the model will also have to guess.

Schemas: get them right or pay forever

Every wrong-shape call costs the user a turn and the operator credibility. Defensive schema design pays back many times over.

• Required vs optional: only require fields you actually require. Optional with a sensible default is the model's friend.
• Enums beat free strings. severity: 'low' | 'medium' | 'high' is hit every time; severity: str will get "normal" and "medium-high" and 12 other variants.
• Dates: pick one format and put it in the description. ISO 8601 with explicit timezone is the safe bet. "2026-05-27T10:00:00Z", not "tomorrow at 10".
• Ranges: state them. temperature: float (0.0 to 2.0). Without the range, models clamp to their priors and you get 0.7 forever.
• No arbitrary dicts. If the input is { k: v } open-ended, define a list of {key: str, value: str} records. Open dicts produce empty dicts.

Output shapes

• Be consistent. If a tool returns JSON, every call returns the same top-level shape, even on empty results.
• Errors are not return values. Raise. Don't return { "error": "..." } — the model has no convention for noticing it.
• Truncate. A tool that dumps 200KB of HTML burns context for no gain. Pre-process, summarize, or paginate.

Debugging

stdio servers

The Inspector is the official debugging tool. It is an Electron app that talks to your server like a client would and shows the wire traffic.

# launch your server under the Inspector
npx @modelcontextprotocol/inspector python my_server.py
# then open the URL it prints (usually http://localhost:5173)

Use it to confirm tools/list matches what you intended, to exercise tool calls with hand-crafted arguments, and to watch what your server actually returns.

When the client fails to load the server

• Stray writes to stdout. Anything that isn't valid JSON-RPC on stdout breaks the protocol. The single most common bug. Audit every print, console.log, logging.basicConfig (default writes to stderr — fine; but check).
• Wrong Python: the client launches python from its own PATH. If your tool needs a venv, point the client config at the venv's python directly, not at python.
• Slow startup. Some clients time out after ~10s. Defer heavy imports until the first tool call.
• Permission denied on the script. chmod +x your_server.py for executables; or have the client invoke the interpreter explicitly.

When tools never get called

• Read your tool description and ask: did I say WHEN to use it? Vague descriptions get skipped.
• Check the model's tool list at runtime. Some clients cap the number of advertised tools. If you ship 40, the model may see only the first 20.
• Name collisions across servers. If two servers both expose search, the model picks one and ignores the other. Prefix when in doubt.

Deployment: Claude Desktop

Claude Desktop reads claude_desktop_config.json on launch. macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "weather": {
      "command": "uvx",
      "args": ["weather-mcp"],
      "env": { "WEATHER_API_KEY": "..." }
    },
    "local-py": {
      "command": "/Users/me/proj/.venv/bin/python",
      "args": ["/Users/me/proj/server.py"]
    }
  }
}

Restart Claude Desktop after editing. The slider icon (bottom-right of the prompt box) lists loaded servers. A red dot means startup failed; click it for the error.

Deployment: Claude Code

Claude Code stores MCP server configs in ~/.claude.json under the mcpServers key, with the same shape as Claude Desktop's config. The CLI also accepts ad-hoc additions:

# add a stdio server for the current project
claude mcp add weather -- uvx weather-mcp

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

# list servers visible to the current project
claude mcp list

Project-scoped servers live in .mcp.json at the project root and are committed to the repo, so collaborators get the same toolset. User-scoped servers live in ~/.claude.json and follow you across projects.

Deployment: hosted HTTP server

If you are shipping a public server, the bare minimum stack is:

1. A small VM or container platform (Fly, Railway, Render, Cloudflare Workers if your runtime fits).
2. TLS in front of your server. The MCP HTTP spec assumes TLS for remote use; do not run plain HTTP on the public internet.
3. A health endpoint (GET /health returning 200) so the platform can route traffic only to live instances.
4. Structured logs to stderr or a log drain. Include the JSON-RPC id of each request so you can correlate across multi-turn sessions.
5. Rate limits at the edge. A single misbehaving client can otherwise melt your upstream.

Auth checklist

• If personal-use: a single static bearer token is fine, rotated monthly.
• If multi-user: implement the MCP OAuth 2.1 flow or front the server with an existing OAuth proxy.
• If both: separate the bearer-token endpoint from the OAuth endpoint at the URL level so misconfigured clients fail loudly, not silently.

Distribution: how users find you

• PyPI / npm: publish the server as a package. uvx <pkg> and npx <pkg> are the canonical user invocations. A README with a copy-paste Claude Desktop config block doubles install rate.
• Public registries: the community keeps a few directories (modelcontextprotocol's servers repo on GitHub, Smithery, PulseMCP). Submitting takes ten minutes and is worth it.
• Your own README: include three things at the top — the one-line description, the config block, and one example prompt. Nothing else matters until the user has those.
• Versioning: semver. Bump major on schema breaks (tool removed, required field added). Models tolerate added optional fields silently; they break on removed tools loudly.

Patterns and anti-patterns

Patterns that work

• Wrap one upstream cleanly. The best servers do one thing: GitHub, Postgres, a single SaaS. Resist the temptation to bundle.
• Read-then-write tools. Pair list_issues with create_issue, read_file with edit_file. The model uses read to ground itself before writing.
• Dry-run flags. For destructive tools, accept a dry_run: bool = false and return what would happen. Models love being asked to confirm.
• Idempotency keys. For create-style tools, accept an optional idempotency_key so re-tries don't duplicate.

Anti-patterns to avoid

• The kitchen-sink server. 40 tools, half overlapping. Models pick wrong, users get confused, you maintain twice as much.
• Tools that take SQL/code/templating-language strings as input. Sometimes necessary, but each one is an injection surface — sandbox before executing.
• Hidden side effects. A tool named get_user should not also create a user record if one is missing. The name is a promise.
• Auto-confirm on destructive actions. delete_database should never be a single tool call. Pair with confirm_delete_database(token) where the token comes from the first call's output.
• Returning raw upstream payloads. Pass-through tools dump kilobytes of unused fields into the model's context. Project to the fields that matter.

Security checklist

• Treat all tool inputs as untrusted. The model is a confused deputy; a malicious prompt can synthesize hostile inputs.
• Sandbox shell-execution and code-execution tools. subprocess.run(shell=True) with model-supplied arguments is a remote-code-execution sink.
• Path-traversal: if a tool takes a file path, resolve it and confirm it lives inside the directory you intend. pathlib.Path(p).resolve().is_relative_to(root) is the cheap test.
• SQL: parameterize. No string interpolation, ever. The model will produce injectable strings if you let it.
• Network egress: if a tool fetches a URL the model supplies, block the metadata IP ranges (169.254.169.254 et al.) and localhost. SSRF is the classic AI-app vulnerability.
• Rate limits per tool. A model in a loop can exhaust an API quota in seconds. Add a per-session call counter.
• Logging: redact secrets in arguments and outputs before persisting.

Testing

Three layers, in order of importance:

1. Unit tests on the tool functions themselves, called directly. This catches 90% of bugs at near-zero cost.
2. Integration tests using the SDK's in-process client. Both Python and TypeScript SDKs ship a test client you can wire to the server in the same process — no transport involved.
3. End-to-end tests with the Inspector or a script that drives the actual stdio transport. Catches transport bugs (stray stdout writes, malformed JSON-RPC).

# Python: in-process integration test
import pytest
from mcp.shared.memory import (
    create_connected_server_and_client_session,
)
from my_server import mcp

@pytest.mark.asyncio
async def test_get_forecast():
    async with create_connected_server_and_client_session(
        mcp._mcp_server
    ) as (_, client):
        result = await client.call_tool(
            "get_forecast", {"city": "Mumbai"}
        )
        assert "Mumbai" in result.content[0].text

Performance

• Cold start: imports dominate. Defer heavy imports (pandas, torch, big API clients) into the first tool that needs them.
• Per-call latency: the model waits for your tool. A 3-second tool turns a 5-call agentic loop into 15 seconds of wall-clock. Cache, batch, or stream where possible.
• Memory: long-running stdio servers leak. Restart-on-interval is acceptable; the client will reconnect.
• Concurrency: stdio servers handle one request at a time by default. If your tool is I/O-bound (network, disk), use async — FastMCP supports async def tools natively.
• Output size: every byte returned is a token in the model's context. The cheap fix is to return less; the right fix is to return more useful less.

Versioning and breaking changes

Treat your tool surface like a public API. Models trained against an old surface still work against a new one only if you add, not remove.

If you must break: document the migration in the README, and consider shipping the old and new tool side-by-side for one release so users can update at their pace.

Glossary

Further reading

• modelcontextprotocol.io — the official spec and docs. Read the spec at least once end-to-end before shipping.
• github.com/modelcontextprotocol/python-sdk — Python SDK source. The examples directory is high-quality.
• github.com/modelcontextprotocol/typescript-sdk — TypeScript SDK source.
• github.com/modelcontextprotocol/servers — community reference servers. Read three before writing your first.
• github.com/modelcontextprotocol/inspector — the debugger.
• The Anthropic engineering blog post on writing good tools (search 'writing tools for claude') is the best short read on tool-description design.

Bookmark all six. You will reference them while building, every time.