How MCP Server Toolkit works

Two transports, one plugin contract. The stdio transport reads JSON-RPC messages from standard input, dispatches them, and writes results to standard output, framed by Content-Length headers exactly as the MCP spec defines. The HTTP transport listens on a configurable port and exposes /mcp as the streamable HTTP endpoint with SSE as the streaming back-channel.

Both implementations build the same internal Request object before anything else runs. From the perspective of the auth layer and the plugin layer, the transport is invisible. This is what lets a single plugin module work in both Claude Desktop (over stdio) and a hosted Vercel deployment (over HTTP) without modification.

OAuth 2.1 with PKCE. The toolkit ships with no opinion about which provider you use; we have working examples for Auth0, Clerk, Logto, and a self-hosted Hydra. The verifier caches the provider’s JWKS for fifteen minutes, decodes the access token, validates the issuer and audience, extracts the scopes, and attaches them to the Request object.

Tools declare their required scope in their decorator. The scope decorator runs after auth but before the tool body. If a tool decorated @tool(scope="write") is invoked without that scope, the call is rejected with an MCP-compliant error. This means write-protected tools (Postgres mutations, GitHub PR creation, filesystem writes) can sit safely next to read-only tools without separate routing.

A plugin is a Python class with a small surface. name identifies it. tools, resources, and prompts declare what it offers. lifespan is an optional async context manager that runs at server start (acquire a database pool, warm a cache, fetch a schema) and runs again on shutdown (close, flush, release).

Plugins are discovered from a configurable list of paths. Each plugin is loaded once at server boot. Hot reload is intentionally not supported , plugin code is trusted, plugin failures crash the server loudly, and the operator restarts. This is the boring, correct choice. It is also the choice that means you can statically analyse the running set of plugins.

Every tool invocation creates a span. The span name is {plugin}.{tool}. Attributes include scope, argument size, the user (when authenticated), and the outcome (success, error, denied). Logs emitted from inside the tool body inherit the trace ID; structured log output is JSON. Metrics are derived from spans by the OTel collector , request count and latency histogram per tool come for free.

OTLP is the only export format. Point it at Tempo, Honeycomb, Datadog, Grafana Cloud, or anything else that speaks OTLP. There is no custom format and no agent installed in the container.

Pydantic Settings reads the environment, type-checks each value, and exposes a single typed configuration object to the rest of the app. Secrets are SecretStr so accidental string interpolation is rejected. The example .env documents every variable; the schema makes it impossible to start the server with a missing required value.

For Vault and AWS Secrets Manager users, an optional secret-resolver layer sits in front of Pydantic Settings: write AWSSM:my/path as a value and the resolver fetches it at boot. The resolver is opt-in; the default path is plain environment variables.

Filesystem. Sandboxed read, write, list, and search across an allow-listed root. Path traversal is rejected by canonicalising paths and re-checking. MIME detection by libmagic. Maximum file size enforced before read. Write scope required for any mutation.

Postgres. Schema introspection (read scope). Parameterised queries with statement timeouts. Read-only mode rejects DDL and DML at parse time using a deny-list of tokens that is conservative by design. Read-write mode requires the write scope.

GitHub. Authenticated with a fine-grained PAT. Issues, pull requests, file contents, comments. Rate-limit-aware: when GitHub returns the rate-limit headers, the plugin sleeps with jitter and retries up to a budget configurable per request.

SarmaLink. Calls the SarmaLink-AI failover stack as a sub-tool. Lets a calling agent invoke any of the thirty-six engines via a single MCP tool. Useful for delegating one part of a workflow to a different model than the calling agent.

Every push runs ruff (lint), mypy strict (types), pytest (unit and integration), and a smoke test that boots the server in both transports and exercises a representative tool. The Docker image is built and tagged on every release. The release process is a one-line GitHub Actions trigger; semver is enforced by the changelog tooling.