Skip to main content
Glama

mcp-server-toolkit

CI CodeQL Python MCP SDK License

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; alg: none and HMAC-with-the-public-key are refused. Protected-resource metadata (RFC 9728) tells clients where to sign in.

auth.py

Authorization

Each tool declares its scopes. Callers only see tools they may use; a call without the scope gets HTTP 403 insufficient_scope so the client can step up, and the guard enforces the same rule on every transport.

policy.py, server.py

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.

store.py

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.

ratelimit.py, policy.py

Safe retries

create_ticket takes an idempotency key; closing twice with the same resolution is a no-op. Annotations say which tools are read-only, destructive or idempotent.

tools.py

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.

tools.py, store.py

Observability

One JSON audit line per call (argument names and a hash, never values), Prometheus metrics by tool and outcome, /healthz, /readyz.

logs.py, metrics.py

API stability

schemas/contract.json holds every tool's schemas, scopes and annotations; CI fails if the server drifts from it.

cli.py

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.

Dockerfile, deploy/

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_scope over HTTP with the right WWW-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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients to search and manage customer support tickets, customer records, and knowledge base articles, with read-only and human-approved write workflows.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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.
      1
      MIT