MCP Server Development

Guide for designing and building MCP (Model Context Protocol) servers that connect Claude to external tools, APIs, and data sources.

Overview

MCP servers bridge Claude with external systems using a standardized protocol. Three primitives are available:

Phase 1: Discovery

Before coding, understand the use case. Ask these questions:

1. What does it connect to?

2. Who will use it?

• Just me / my team → Local stdio acceptable
• Anyone who installs it → Remote HTTP (preferred) or MCPB
• Claude desktop with UI widgets → MCP app

3. How many distinct actions?

• Under ~15 actions → One tool per action
• Dozens to hundreds → Search + execute pattern

4. Does a tool need user input mid-call?

• Simple forms (pick, enter, confirm) → Elicitation (spec-native)
• Rich UI (charts, search, dashboards) → MCP app widgets
• Neither → Plain tool returning text/JSON

5. What authentication does the service use?

• None / API key → Straightforward
• OAuth 2.0 → Remote server with CIMD or DCR support

Phase 2: Recommend Deployment Model

Based on discovery answers, recommend ONE path:

⭐ Remote HTTP Server (Default)

Hosted service speaking MCP over streamable HTTP. Best for cloud API wrappers.

Benefits:

• Zero install friction - users add a URL
• One deployment serves all users
• OAuth flows work properly
• Works across Claude desktop, Claude Code, Claude.ai

Choose unless server must touch local machine.

MCPB (Bundled Local Server)

Local server packaged with its runtime. No Node/Python needed on user machine.

Choose when server must run on user's machine:

• Reads local files
• Drives desktop apps
• Talks to localhost services
• Needs OS-level access

Local stdio (Prototypes Only)

Script launched via npx / uvx. Fine for personal tools and prototypes.

Not recommended for distribution - users need runtime, no update mechanism.

Phase 3: Pick Tool Design Pattern

Pattern A: One Tool Per Action (Small Surface)

When action space is small (< ~15 operations), each gets a dedicated tool.

create_issue   — Create a new issue
update_issue   — Update an existing issue
search_issues  — Search issues by query
add_comment    — Add a comment

Benefits: Claude reads tool list once, knows exactly what's possible.

Pattern B: Search + Execute (Large Surface)

When wrapping large APIs (dozens+ endpoints), use TWO tools:

search_actions  — Return matching actions with IDs and schemas
execute_action  — Run an action by ID with params

Benefits: Server holds catalog internally, context stays lean.

Hybrid: Promote 3-5 most-used actions to dedicated tools.

Phase 4: Pick Framework

Both produce identical wire protocol.

Phase 5: Scaffold Server

FastMCP (Python)

from fastmcp import FastMCP

mcp = FastMCP("server-name")

@mcp.tool
def my_tool(query: str) -> dict:
    """Tool description Claude sees."""
    return process(query)

if __name__ == "__main__":
    mcp.run()  # stdio (default)
    # mcp.run(transport="http", port=8000)  # HTTP

TypeScript SDK

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

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

server.tool("myTool", { query: z.string() }, async ({ query }) => ({
  content: [{ type: "text", text: JSON.stringify(process(query)) }]
}));

server.connect(transport);

Phase 6: Test and Publish

Testing

# MCP Inspector - official testing tool
npx @modelcontextprotocol/inspector uv run python -m my_mcp

Critical: Log to stderr, NOT stdout (stdout is the protocol).

Testing Before Release:

1. Test ALL tools with MCP Inspector before releasing
2. Test with actual provider (e.g., real IMAP server) if wrapping external APIs
3. Verify environment variables are passed correctly
4. Check provider-specific quirks (see Provider Quirks section)

Claude Code Plugin Deployment

When bundling MCP servers in Claude Code plugins:

The cwd Bug (Issue #17565)

CRITICAL: Claude Code ignores the cwd field in .mcp.json. Always use the bash -c workaround:

{
  "mcpServers": {
    "my-server": {
      "command": "bash",
      "args": ["-c", "cd \"${CLAUDE_PLUGIN_ROOT}/my-server\" && exec uv run python -m my_mcp"]
    }
  }
}

Dependency Management

Use uv run for portable dependency management:

"command": "bash",
"args": ["-c", "cd \"${CLAUDE_PLUGIN_ROOT}/server\" && exec uv run python -m server"]

This ensures dependencies are automatically installed from pyproject.toml.

Environment Variables

Only include required environment variables in .mcp.json. Optional variables should use defaults in code:

# Bad - will fail if EMAIL_OAUTH2_TOKEN is empty
oauth2_token: str = Field(alias="OAUTH2_TOKEN")

# Good - optional with default
oauth2_token: str | None = Field(default=None, alias="OAUTH2_TOKEN")

For Pydantic settings, use env_parse_none_str="" to treat empty strings as None:

model_config = SettingsConfigDict(
    env_prefix="MY_",
    env_parse_none_str="",  # Empty strings become None
)

Provider Quirks

When wrapping external services, test with the actual provider:

Pre-submission Checklist

• Read/write tool split for destructive operations
• Required annotations on all tools
• Tool names under 128 characters
• No prompt injection in tool output
• Input validation on all parameters
• Tested with MCP Inspector
• Tested with actual provider (not just mocks)

Distribution

• Submit to Anthropic Directory
• Create plugin wrapper for skills
• Document installation clearly
• Require uv for dependency management

Security Essentials

Additional Resources

Reference Files

Consult these for detailed implementation guidance:

• references/fastmcp-patterns.md — FastMCP decorator patterns, type hints, context injection
• references/security-best-practices.md — Input validation, credential management, path traversal prevention
• references/testing-debugging.md — MCP Inspector, stderr logging, CI/CD integration
• references/deployment-options.md — stdio, HTTP/SSE, Cloudflare Workers, Docker, MCPB

External Links

• MCP Specification
• FastMCP Documentation
• MCP Python SDK

Source: christophevg/c3 — distributed by TomeVault.