Skip to main content
Glama

mcp-server-patterns

A reference implementation of production patterns for a Python MCP (Model Context Protocol) server in front of a data platform.

This is a reference implementation running against a fake in-memory backend. It is not any vendor's code, does not call any real API, and contains no proprietary material. The tools, data and workspaces are synthetic.

The problem

Data platform vendors increasingly ship managed MCP servers. They cover the common surface well and leave gaps: the APIs they do not expose, plus the policy you need around them (multiple workspaces, destructive-action safety, context budgets). The usual answer is a small custom MCP server that sits beside the managed ones and fills the gaps.

A custom server with 40 or more tools gets messy fast if every tool re-implements auth, routing, paging and safety. This project shows one way to keep tools tiny and push cross-cutting policy into one pipeline. The example has 15 tools across catalog, jobs, model serving, vector search and compute lifecycle. The same shape scales to many more.

Related MCP server: fde-assessment

Architecture

  MCP client (LLM host)
        |  JSON-RPC 2.0, one message per line
        v
  +-------------------------------+
  | rpc.py   JsonRpcServer        |  initialize, ping, tools/list, tools/call
  | (stdlib; swappable transport) |  pure handle(dict) -> dict
  +---------------+---------------+
                  |
                  v
  +-------------------------------------------------------------+
  | registry.py   ToolRegistry.call()  - the policy pipeline     |
  |                                                             |
  |  1 validate args against schema generated from type hints   |
  |  2 resolve workspace  --> workspaces.py (WORKSPACE_<N>_TOKEN)|
  |  3 capability gate    --> capabilities.py (cached probe)    |
  |  4 destructive gate   (confirm=true / dry_run=true)         |
  |  5 run tool fn(ctx, ...)           <-- tools.py             |
  |  6 shape: size cap, cursor repair  --> shaping.py           |
  |  7 redact secrets                  --> redaction.py         |
  +---------------+---------------------------------------------+
                  |
                  v
  +-------------------------------+
  | backend.py  FakeBackend       |  tables, jobs, models, vector index,
  | (replace with a real client)  |  clusters; one instance per workspace
  +-------------------------------+

Every call returns a dict with a status: ok, dry_run, confirmation_required, unavailable or error. Only error sets isError on the MCP response.

Design decisions

  1. A registry with a decorator, not hand-written handlers. Tools are def name(ctx, ...) functions. The registry generates the JSON schema from type hints (Optional, Literal, list[str], Annotated[..., "description"]) and records metadata (read_only, destructive, idempotent, requires). Schemas cannot drift from signatures, and policy applies uniformly because there is one call path.

  2. Multi-workspace routing is a registry concern, not a tool concern. Every workspace-scoped tool gets an optional workspace argument added automatically. Tokens come from WORKSPACE_<NAME>_TOKEN environment variables (headless, no interactive login), are read on each call so rotation works, are registered with the redactor, and are never logged or returned.

  3. Graceful degradation over exceptions. Workspaces differ in what they support. A tool declaring requires="vector_search" gets a cached capability probe; if the feature is missing the caller receives {"status": "unavailable", "feature": ..., "reason": ...}. The model can adapt (use another workspace, skip a step) instead of seeing a stack trace. A probe that itself fails is treated as unavailable.

  4. Confirm gates for destructive tools. A tool marked destructive=True gets confirm and dry_run arguments added by the registry. Without confirm=true nothing runs and the response says how to proceed. dry_run=true runs the tool against a read-only backend wrapper that raises on any mutating method, so a preview cannot change state even if a tool is written badly. dry_run wins over confirm. confirm must be a real boolean; the string "true" is rejected.

  5. Output caps and cursor pagination. Lists use opaque cursors with a clamped page size. A global character cap trims items to the largest prefix that fits, flags truncated, and rewrites next_cursor so the caller resumes with no gaps. Long strings are clipped. Tools cannot flood the context window even when written carelessly.

  6. Redaction in depth. Exact secret values (registered when read), sensitive key names (token, api_key, authorization and similar, but not max_tokens), and regexes for Bearer and key=value text. It applies to every result and, through a logging filter, every log line. Logs record argument names, not values, and exceptions are logged by type only.

  7. A transport-agnostic core and a stdlib adapter. The registry and router know nothing about JSON-RPC. rpc.py is a small stdlib stdio server, so the project runs with zero dependencies. stdout is reserved for the protocol (the server redirects stray print to stderr). To use the official mcp SDK, wire its list and call handlers to registry.list_tools() and registry.call(); that adapter is not included.

Run

Requires Python 3.10 or later. No runtime dependencies.

python -m mcp_patterns.server --demo

Then send newline-delimited JSON-RPC on stdin:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"drop_table","arguments":{"table":"orders","dry_run":true}}}' \
  | python -m mcp_patterns.server --demo

--demo configures two fake workspaces (dev, with every feature, and legacy, without model serving or vector search) and sets placeholder tokens if the environment has none. For your own configuration use --config workspaces.json and export a token per workspace:

{"default_workspace": "prod",
 "workspaces": {"prod": {"url": "https://prod.example.invalid"},
                "staging": {"url": "https://staging.example.invalid", "features": ["catalog", "jobs"]}}}

export WORKSPACE_PROD_TOKEN=...      # name is upper-cased; non-alphanumerics become _
export WORKSPACE_STAGING_TOKEN=...

Run the tests:

pip install pytest
python -m pytest -q

Environment: MCP_MAX_OUTPUT_CHARS (default 8000) sets the response cap; MCP_LOG_LEVEL sets the stderr log level.

Add a tool

Add a function to mcp_patterns/tools.py (or any module that imports registry):

@registry.tool(read_only=True, requires="jobs")
def count_failed_jobs(ctx, pipeline: Annotated[Optional[str], "Filter by pipeline."] = None):
    """Count failed job runs, optionally for one pipeline."""
    jobs = ctx.backend.list_jobs("failed")
    return {"failed": sum(1 for j in jobs if pipeline in (None, j["pipeline"]))}

Rules:

  • First parameter is ctx (ctx.backend, ctx.workspace, ctx.dry_run, ctx.require(feature)).

  • Do not declare workspace, confirm or dry_run; the registry owns them.

  • Return plain JSON-serializable data. For lists return paginate(items, cursor, limit) or {"items": [...]} so the output cap can trim them.

  • Raise ToolError(code, message) for expected failures.

  • For a destructive tool use @registry.tool(destructive=True) and, when ctx.dry_run is true, return a description of what would happen rather than acting.

  • Add a method to the backend for the new operation, and add its name to FakeBackend.MUTATING if it changes state.

Layout

mcp_patterns/
  registry.py      decorator, schema generation, validation, call pipeline
  workspaces.py    named workspaces, token env vars, Context
  capabilities.py  cached feature probe
  shaping.py       cursors, pagination, output cap
  redaction.py     redactor and logging filter
  backend.py       FakeBackend and the read-only dry-run wrapper
  tools.py         15 example tools
  rpc.py           stdlib JSON-RPC stdio server
  server.py        entry point
tests/             registry, routing, degradation, safety, redaction, shaping, stdio round trip

License

MIT

Available Tools

15 tools
cancel_jobA
DestructiveIdempotent

Cancel a queued or running job. Requires confirm=true; use dry_run=true to preview.

Inputs: job_id (required), confirm, dry_run, workspace.

describe_tableB
Read-onlyIdempotent

Return the schema and row count of one table.

Inputs: table (required), workspace.

drop_tableA
Destructive

Permanently drop a table. Requires confirm=true; use dry_run=true to preview.

Inputs: table (required), confirm, dry_run, workspace.

get_jobB
Read-onlyIdempotent

Get one job run by id.

Inputs: job_id (required), workspace.

invoke_modelC
Read-onlyIdempotent

Run inference against a served model.

Inputs: model (required), inputs (required), workspace.

list_clustersB
Read-onlyIdempotent

List compute clusters and their state.

Inputs: workspace.

list_jobsB
Read-onlyIdempotent

List pipeline job runs, optionally filtered by status. Paginated.

Inputs: limit, cursor, status, workspace.

list_modelsC
Read-onlyIdempotent

List served models and their state.

Inputs: workspace.

list_tablesB
Read-onlyIdempotent

List tables in the catalog, optionally filtered by name. Paginated.

Inputs: limit, cursor, workspace, name_contains.

list_workspacesA
Read-onlyIdempotent

List configured workspaces and whether a token is set (never the token itself).

Inputs: no named parameters.

run_jobC

Queue a new run of a pipeline. Not destructive, but it does change state.

Inputs: pipeline (required), workspace.

sample_tableB
Read-onlyIdempotent

Return a small synthetic sample of rows from a table.

Inputs: table (required), rows, workspace.

start_clusterC
Idempotent

Start a cluster. Safe to repeat.

Inputs: name (required), workspace.

terminate_clusterA
DestructiveIdempotent

Terminate a running cluster. Requires confirm=true; use dry_run=true to preview.

Inputs: name (required), confirm, dry_run, workspace.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource/action: table inspection, job lifecycle, cluster lifecycle, model listing/invocation, workspace listing, and vector search. Tools like list_tables, describe_table, and sample_table are related but have unambiguous distinctions, and no two tools appear to do the same thing.

    Naming Consistency4/5

    Nearly all tools follow a consistent snake_case verb_noun pattern, and singular/plural resource naming is used conventionally. The only mild deviation is vector_search, which follows a noun_verb form but remains clear and readable.

    Tool Count5/5

    The server exposes 15 tools, which is at the upper end of the ideal range but still well-scoped for a data-platform control surface. Each tool maps to a meaningful operation across tables, jobs, clusters, models, workspaces, or search.

    Completeness3/5

    Core operational coverage is present for listing, inspecting, running/canceling jobs, starting/terminating clusters, and invoking models. However, there are notable gaps such as creating/altering tables, detailed get operations for clusters/models/workspaces, and model deployment/update workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP tool calls with strict schema validation and stdio isolation, while providing a security gateway for tool-level authorization, streaming PII redaction, and model failover routing.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a single MCP endpoint that dynamically discovers, routes, policy-checks, and executes hundreds of MCP tools from any agent, with optional LLM-based routing.
      19 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables external MCP clients to invoke governed tools with schema validation, budgets, policy checks, human approval for side-effecting actions, and prompt-injection quarantine.
      MIT