Architecture

Architecture

graph TD
  C[MCP Client]
  C -->|stdio JSON-RPC| S[stdio transport]
  C -->|streamable HTTP| H[FastAPI HTTP transport]
  S --> R[Tool Registry]
  H --> A[OAuth / API key]
  A --> R
  R --> P1[plugin: filesystem]
  R --> P2[plugin: sarmalink]
  P2 -->|api.sarmalink.ai| SL[SarmaLink-AI]

Loading

Components

File	Responsibility
server.py	Lifecycle, transport selection, plugin auto-import
registry.py	Decorator-based tool registry with schema generation
transports/stdio.py	JSON-RPC 2.0 loop over stdin/stdout
transports/http.py	FastAPI app for streamable HTTP transport
auth/api_key.py	Header-based API key middleware
auth/oauth.py	OAuth 2.1 with PKCE skeleton
telemetry.py	OpenTelemetry spans, structlog config
cli.py	mcp-toolkit run / doctor / init

Tool registration flow

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

The decorator inspects the function signature and generates a JSON Schema for MCP tool advertisement. Required vs optional parameters come from default values.

Transport selection

Stdio: clients launch the server as a subprocess. Used by Claude Desktop, Cursor, IDE plugins.

Streamable HTTP: clients connect over the network. Used by remote agents and team-wide deployments behind a reverse proxy.

Same registry, same plugins, same handlers. Transport is a shell.