Custom MCP Tool Server.

The problem

Click to zoom

What the customer needs

1. Expose internal tools once and reuse them across Claude Code, Claude Desktop, and a custom agent, without rewriting the schema three times.
2. Let a client discover available tools and resources dynamically, without a hardcoded list baked into the app.
3. Keep tool execution scoped and validated, since the server is invoked from model-generated input.

Why naive approaches fail

1. Duplicating the same tool schema as a Messages API custom tool in three different apps means schema drift: one app's version diverges from another's.
2. Trusting tool_use.input at face value inside the handler means the JSON schema is a hint, not an enforcement mechanism - a malformed or adversarial input reaches your handler unvalidated.
3. Running a stdio server exactly as written for a shared/remote use case doesn't work: stdio is a local process pipe, not a network protocol.

The system

Click to zoom

What each part does

4 components, each owns a concept. Click any card to drill into the underlying primitive.

Data flow

Click to zoom

6 steps to production

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("internal-tools")

@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up an order by order_id. Use this when asked about order
    status or contents. Returns a not_found message if the id is unknown."""
    order = db.orders.get(order_id)
    if order is None:
        return f"order_id {order_id} not found"
    return json.dumps(order)

@mcp.resource("config://refund-policy")
def refund_policy() -> str:
    """Current refund policy document, read-only."""
    return open("policy/refund-policy.md").read()

@mcp.tool()
def process_refund(order_id: str, amount: float) -> str:
    """Process a refund for order_id up to the policy cap."""
    if not order_id or not isinstance(order_id, str):
        raise ValueError("invalid order_id")
    if not (0 < amount <= POLICY_CAP):
        raise ValueError(f"amount must be between 0 and {POLICY_CAP}")
    return billing.refund(order_id, amount)

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

# .mcp.json (project root)
# {
#   "mcpServers": {
#     "internal-tools": {
#       "command": "python",
#       "args": ["server.py"]
#     }
#   }
# }
pass

# server: mcp.run(transport="streamable-http")

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://internal-tools.example.com/mcp",
        "name": "internal-tools",
        "authorization_token": os.environ["INTERNAL_TOOLS_TOKEN"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "internal-tools"}],
    messages=[{"role": "user", "content": "Look up order 42"}],
)

The four decisions

Where it breaks

Click to zoom

3 failure pairs. Each maps to an exam-style question - the naive move on the left, the disciplined fix on the right.

Cost & latency

Ship checklist

Two passes. Build-time gates verify the code; run-time gates verify the system in production.

Build-time

1. Tools registered with clear, when-to-use descriptions↗ tool-calling
2. At least one resource for read-only reference content↗ mcp
3. Every handler re-validates input server-side↗ guardrails-and-safety-controls
4. stdio transport wired into .mcp.json for local dev↗ mcp
5. Streamable HTTP transport behind auth for remote/shared use
6. MCP connector beta header (mcp-client-2025-11-20) present when wired into the Messages API

Run-time

• Every tool handler has server-side input validation, not just a JSON schema
• Resource endpoints tested via resources/list and resources/read
• .mcp.json checked into the repo for reproducible local dev
• Remote HTTP transport runs behind authentication, never open
• Tool descriptions reviewed for when-to-call clarity, same bar as Messages API custom tools

Five exam-pattern questions

Frequently asked