mcp-server-toolkit
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-server-toolkit
A production template for Model Context Protocol servers in Python. The SDK makes a tool a decorated function; this repository adds what it takes to put one in front of real users: OAuth resource-server auth, per-tool scopes, tenant isolation, rate limits, timeouts, size limits, an audit log, metrics, a checked tool contract, a container and Kubernetes manifests, all tested end to end.
Reference implementation built on synthetic or public data. It distils patterns from production work into code you can run and read; it is not a client system.
The example domain is a support-ticket system (search, read, create, comment, close). Replace the tools; keep the shape.
What a request goes through
flowchart LR
C[MCP client] -->|Bearer JWT| H[Streamable HTTP /mcp]
H --> RB[Host/Origin check<br/>body size limit]
RB --> AU{token valid?<br/>issuer, audience,<br/>algorithm, expiry}
AU -->|no| E401[401 + resource metadata]
AU --> SU{tool's scope<br/>in token?}
SU -->|no| E403[403 insufficient_scope]
SU --> G[guard middleware]
G --> RL{rate limit<br/>per tenant+user}
RL -->|over| RLE[tool error + retry-after]
RL --> T[tool, under timeout<br/>tenant from token]
T --> SZ{result size}
SZ --> OUT[result]
G -.-> AUD[audit line: who, what, outcome,<br/>argument hash, never values]
G -.-> M[Prometheus metrics]Concern | How | Where |
Authentication | The server is an OAuth 2.1 resource server for your IdP. JWTs verified against its JWKS with pinned issuer, audience (RFC 8707) and asymmetric algorithms; |
|
Authorization | Each tool declares its scopes. Callers only see tools they may use; a call without the scope gets HTTP 403 |
|
Tenancy | The tenant comes from a token claim, never an argument. Every query is scoped by it; another tenant's ticket is indistinguishable from a missing one. |
|
Abuse and cost | Token buckets per tenant and user, separate for reads and writes, in memory or shared across replicas in Redis. Tool timeouts, result-size and request-size limits, cursor pagination. |
|
Safe retries |
|
|
Prompt injection | Tool descriptions and the prompt mark ticket text as user-written data. Full-text search quotes every word, so input is never query syntax. |
|
Observability | One JSON audit line per call (argument names and a hash, never values), Prometheus metrics by tool and outcome, |
|
API stability |
|
|
Deployment | Non-root image that runs with a read-only root filesystem; Compose stack with two replicas sharing Redis; Kustomize manifests with HPA, PDB, zone spread, restricted Pod Security and a NetworkPolicy. |
|
Related MCP server: Zendesk MCP Server
Quick start
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
mcpkit dev-keys # a local signing key and JWKS in dev/ (never for production)
mcpkit serve # http://127.0.0.1:8000/mcp
TOKEN=$(mcpkit dev-token --scopes "tickets:read tickets:write")Connect any MCP client to http://127.0.0.1:8000/mcp with Authorization: Bearer $TOKEN. From Python:
import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client
async with httpx2.AsyncClient(headers={"Authorization": f"Bearer {token}"}) as http:
async with Client(streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http)) as c:
created = await c.call_tool("create_ticket", {"title": "Sync stuck", "body": "...", "idempotency_key": "retry-001"})For a desktop client over stdio, mcpkit serve --transport stdio runs as a local principal whose tenant and scopes come from MCPKIT_STDIO_TENANT and MCPKIT_STDIO_SCOPES.
Production
Point it at your IdP and run several replicas:
MCPKIT_ISSUER=https://idp.example.com
MCPKIT_AUDIENCE=https://mcp.example.com/mcp # the URL clients use; tokens must carry it as aud
MCPKIT_JWKS_URL=https://idp.example.com/.well-known/jwks.json
MCPKIT_REDIS_URL=redis://redis:6379/0 # one rate-limit bucket per principal across replicas
MCPKIT_ALLOWED_HOSTS='["mcp.example.com"]'docker compose up runs two replicas and Redis locally. deploy/k8s is a Kustomize base. All settings are in config.py.
Performance
32 clients over Streamable HTTP, each call with an RS256 token verified on arrival, against one uvicorn worker and SQLite: 3,200 tool calls at 225 a second, 0 errors, p95 200 ms, with clients and server sharing one busy two-core machine. A principal bursting 200 reads gets 121 through and 79 refused with a retry-after. Details in docs/performance.md; make bench reproduces it.
Tests
make check runs ruff, mypy (strict), the contract check and 40+ tests with coverage above 85%, including:
tokens with a wrong audience, issuer, key, algorithm, or expiry; the HMAC key-confusion attack;
tools hidden and refused without scope; 403
insufficient_scopeover HTTP with the rightWWW-Authenticate;tenant isolation in-process and over HTTP; idempotent create and close; input validation; search input that looks like FTS syntax;
rate limits per principal and for writes; a shared bucket across two Redis-backed replicas; timeouts; result and body size limits; DNS-rebinding protection;
the audit line carrying no argument values; metrics; the stdio transport as a subprocess.
Design decisions
ADR 1 resource-server auth · ADR 2 scopes per tool · ADR 3 limits and audit · ADR 4 the contract as a file
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Remote MCP server for managing Muninx tickets, messages, ticket search, and support analytics.
Helpdesk tickets from your AI: find, reply, take, hold, complete — within your own role. OAuth.
Customer support for MCP servers: work your tickets from Claude or any MCP client. Service key auth.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to access and manage an internal support ticket queue through MCP tools, resources, and prompts, including searching and viewing tickets, adding comments, closing tickets with confirmation, reading knowledge base articles, and viewing queue summaries over OAuth-secured Streamable HTTP.-
- FlicenseNot gradedqualityAmaintenanceEnables retrieval and management of tickets and comments, ticket analysis and response drafting, and access to Help Center articles as a knowledge base via MCP.-
- AlicenseBqualityCmaintenanceEnables MCP clients to search and manage customer support tickets, customer records, and knowledge base articles, with read-only and human-approved write workflows.81MIT
- AlicenseNot gradedqualityCmaintenanceExposes a multi-tenant helpdesk over MCP, enabling tool-based ticket, document, and notification operations while applying configurable authorization, tenant-isolation, input-handling, and rate-limit defenses.1MIT