A production-grade MCP server, ready on day one.
The Model Context Protocol starter you would have written in week three.
MCP Server Toolkit is a plugin-first server that speaks the Model Context Protocol over both stdio and streamable HTTP. OAuth, OpenTelemetry, structured logging, healthchecks, and four production plugins ship in the box. Built in Python 3.12 with FastAPI and the official mcp SDK.
Why this exists
The Model Context Protocol is the cleanest standard the AI ecosystem has produced for tool use. The official SDKs are excellent. The reference servers are deliberately minimal. Anyone shipping MCP into a real product still has to write the same thousand lines of OAuth, telemetry, plugin loading, lifecycle management, and CI scaffolding before they can do anything interesting.
Every team I have worked with rebuilds the same stack: a FastAPI app, a plugin discovery loop, a way to gate sensitive tools behind OAuth scopes, a way to fan tools out across stdio for desktop clients and streamable HTTP for hosted clients. Most of the time the implementation drifts and the tests come last.
MCP Server Toolkit is the consolidation. One server, one plugin contract, both transports, OAuth on the sensitive ones, OpenTelemetry across the lot. Fork it, drop in your own plugins, deploy it. The boring work is already done.
What it does
Every feature below ships in the public repository today. Clone, configure, run.
Plugin architecture
Each plugin is a Python package that exports a Plugin object: tools, prompts, resources, lifecycle hooks. The server discovers them at boot and registers them with the MCP runtime.
Two transports
Stdio for desktop clients (Claude Desktop, IDE plugins). Streamable HTTP with SSE for hosted clients. The plugin code is identical between them.
OAuth 2.1 with PKCE
Drop-in OAuth provider integration. Scope-gated tools , write operations require write scope, read tools stay open. JWKS cached, refresh handled.
OpenTelemetry baked in
Every tool invocation emits a span. Logs, metrics, and traces correlate via trace ID. Wire up OTLP and you have a flame graph for every prompt.
Filesystem plugin
Sandboxed read, write, list, and search across an allow-listed root. Path traversal prevention, MIME detection, size caps.
GitHub plugin
Issues, PRs, file reads, comments. Authenticated with a fine-grained PAT. Rate-limit-aware with exponential backoff.
Postgres plugin
Read-only and read-write modes. Schema introspection, parameterised queries, statement timeouts. Dangerous keywords blocked when in read-only mode.
SarmaLink plugin
Calls into the SarmaLink-AI failover stack as a sub-tool. Lets a calling agent borrow the 36-engine routing without adopting the rest.
Secrets via env
No hard-coded credentials. Twelve-factor configuration via Pydantic settings. Optional Vault and AWS Secrets Manager adapters.
Healthchecks + readiness
Kubernetes-style liveness and readiness probes for the HTTP transport. Plugin-level health endpoints aggregated into one report.
Tech stack
Architecture, in one diagram
The whole system on a single screen. Every box maps to a real folder in the repo.
┌──────────────────────────────────────────────────────────────────────┐
│ MCP Client (Desktop or Hosted) │
│ stdio ◀────────────────────▶ streamable HTTP / SSE │
└─────────────┬───────────────────────────────────────┬─────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────┐
│ MCP Server Toolkit (FastAPI app) │
│ ┌────────────────────────────────────────────────┐ │
│ │ Transport router · stdio · HTTP+SSE │ │
│ └──────────────────┬─────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ OAuth 2.1 middleware + scope check │ │
│ └──────────────────┬─────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Plugin registry · discovers + lifecycles │ │
│ │ filesystem · postgres · github · sarmalink │ │
│ └──────────────────┬─────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────┐ │
│ │ OpenTelemetry · spans, metrics, structured logs│ │
│ └────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘Quick start
From clone to first request in under five minutes.
git clone https://github.com/sarmakska/mcp-server-toolkit.git cd mcp-server-toolkit
uv sync # creates the venv, installs deps cp .env.example .env # set OAUTH_*, DATABASE_URL, GITHUB_TOKEN
uv run mcp-toolkit serve --transport http # streamable HTTP on :7800 # or uv run mcp-toolkit serve --transport stdio # for desktop clients
curl http://localhost:7800/healthz # readiness check curl http://localhost:7800/mcp/tools \ -H "Authorization: Bearer $TOKEN" # list tools, OAuth-gated
Where it fits
The patterns this repository was built around.
Internal AI assistants
Give a hosted assistant safe access to your company filesystem, Postgres replicas, and GitHub. Scope-gated. Audited via OTel.
Desktop tool servers
Ship a stdio MCP server for IDE plugins. The same plugin code that runs over HTTP works locally with no changes.
Agent platforms
Use the toolkit as the tool layer for an agent orchestrator. Plug it into Agent Orchestrator and you get tool budgets and replay for free.
Edge MCP gateways
Run as a thin gateway that authenticates clients then fans tool calls out to internal services. SarmaLink plugin for AI, Postgres for data.
Related products
The wider Sarma Linux toolkit. Every project ships with the same opinions: open source, MIT, real depth, no marketing fluff.
Stand up an MCP server in under five minutes.
Clone the repo, follow the four-step quick start, ship something real.