A production-grade MCP server, ready on day one.

# src/mcp_toolkit/plugins/myplugin/handlers.py
from ...registry import registry

@registry.tool("search_docs", description="Search internal docs")
async def search_docs(query: str, limit: int = 10) -> dict:
    return {"results": [...]}

# query is required (no default), limit is optional.
# The generated schema sets additionalProperties: false,
# so unexpected arguments are rejected at the boundary.

@registry.tool(
    "get_weather",
    description="Current weather for a city",
    output_schema={
        "type": "object",
        "properties": {
            "city": {"type": "string"},
            "temperature_c": {"type": "number"},
            "conditions": {"type": "string"},
        },
        "required": ["city", "temperature_c", "conditions"],
    },
)
async def get_weather(city: str) -> dict:
    return {"city": city, "temperature_c": 14.0, "conditions": "partly cloudy"}

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | uv run mcp-toolkit run --transport stdio

MCP_AUTH=oauth
MCP_OAUTH_ISSUER=https://your-id-provider.com
MCP_OAUTH_AUDIENCE=mcp-toolkit

# Optional: skip discovery
MCP_OAUTH_JWKS_URI=https://your-id-provider.com/.well-known/jwks.json

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/mcp \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

MCP_OAUTH_CLIENT_ID=your-public-client-id
MCP_OAUTH_REDIRECT_URI=http://127.0.0.1:8765/callback

uv run mcp-toolkit login \
  --issuer https://your-id-provider.com \
  --client-id your-public-client-id
# Prints the access token to send as Authorization: Bearer ...

They serve different agents. Desktop and IDE clients launch the server as a subprocess and exchange JSON-RPC over stdin and stdout. Hosted agents call POST /mcp over the network. Routing both through one protocol.dispatch is what guarantees a tool behaves identically in either deployment.

The registry inspects type hints with typing.get_type_hints and maps each parameter to a JSON Schema fragment. str becomes string, int becomes integer, list[str] becomes an array of strings, X | None is treated as the inner type. Parameters without a default are required. additionalProperties is set to false.

Yes. The decorator rejects a sync function at registration time. Use httpx.AsyncClient and async database drivers. If you must call blocking code, wrap it in loop.run_in_executor. Log through structlog rather than print so stdout stays a clean JSON-RPC channel.

Argument validation failures map to JSON-RPC -32602. Unknown tools or methods map to -32601. Handler exceptions return a tools/call result with isError set to true and the exception message attached, so the agent sees what went wrong rather than the session crashing.

Yes. mcp-toolkit login discovers authorisation server metadata, generates a PKCE pair, opens the browser, captures the redirect on a one-shot loopback listener, exchanges the code for a token, and prints it. There is no third-party broker.

The JWKS validator caches keys and refetches on rotation, so a key roll at your identity provider does not need a server restart. The kid in the JWT header points the validator at the right key.

No. The container runs as a non-root user, exposes a built-in health check, and reads every setting from the environment with an MCP_ prefix. Healthchecks at /health are always open, so they work as liveness and readiness probes without any auth bypass.

Python is where the MCP reference SDK ships first and the tool-authoring ecosystem (Pydantic, jsonschema, OpenTelemetry, FastAPI) is mature. The protocol layer is small enough that a TypeScript twin would be a port, not an integration.