mcp-server-patterns
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-patterns list running jobs in workspace analytics"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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.Multi-workspace routing is a registry concern, not a tool concern. Every workspace-scoped tool gets an optional
workspaceargument added automatically. Tokens come fromWORKSPACE_<NAME>_TOKENenvironment variables (headless, no interactive login), are read on each call so rotation works, are registered with the redactor, and are never logged or returned.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.Confirm gates for destructive tools. A tool marked
destructive=Truegetsconfirmanddry_runarguments added by the registry. Withoutconfirm=truenothing runs and the response says how to proceed.dry_run=trueruns 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_runwins overconfirm.confirmmust be a real boolean; the string"true"is rejected.Output caps and cursor pagination. Lists use opaque cursors with a clamped page size. A global character cap trims
itemsto the largest prefix that fits, flagstruncated, and rewritesnext_cursorso the caller resumes with no gaps. Long strings are clipped. Tools cannot flood the context window even when written carelessly.Redaction in depth. Exact secret values (registered when read), sensitive key names (
token,api_key,authorizationand similar, but notmax_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.A transport-agnostic core and a stdlib adapter. The registry and router know nothing about JSON-RPC.
rpc.pyis a small stdlib stdio server, so the project runs with zero dependencies. stdout is reserved for the protocol (the server redirects strayprintto stderr). To use the officialmcpSDK, wire its list and call handlers toregistry.list_tools()andregistry.call(); that adapter is not included.
Run
Requires Python 3.10 or later. No runtime dependencies.
python -m mcp_patterns.server --demoThen 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 -qEnvironment: 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,confirmordry_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, whenctx.dry_runis 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.MUTATINGif 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 tripLicense
MIT
Available Tools
15 toolscancel_jobADestructiveIdempotent
Cancel a queued or running job. Requires confirm=true; use dry_run=true to preview.
Inputs: job_id (required), confirm, dry_run, workspace.
describe_tableBRead-onlyIdempotent
Return the schema and row count of one table.
Inputs: table (required), workspace.
drop_tableADestructive
Permanently drop a table. Requires confirm=true; use dry_run=true to preview.
Inputs: table (required), confirm, dry_run, workspace.
get_jobBRead-onlyIdempotent
Get one job run by id.
Inputs: job_id (required), workspace.
invoke_modelCRead-onlyIdempotent
Run inference against a served model.
Inputs: model (required), inputs (required), workspace.
list_clustersBRead-onlyIdempotent
List compute clusters and their state.
Inputs: workspace.
list_jobsBRead-onlyIdempotent
List pipeline job runs, optionally filtered by status. Paginated.
Inputs: limit, cursor, status, workspace.
list_modelsCRead-onlyIdempotent
List served models and their state.
Inputs: workspace.
list_tablesBRead-onlyIdempotent
List tables in the catalog, optionally filtered by name. Paginated.
Inputs: limit, cursor, workspace, name_contains.
list_workspacesARead-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_tableBRead-onlyIdempotent
Return a small synthetic sample of rows from a table.
Inputs: table (required), rows, workspace.
start_clusterCIdempotent
Start a cluster. Safe to repeat.
Inputs: name (required), workspace.
terminate_clusterADestructiveIdempotent
Terminate a running cluster. Requires confirm=true; use dry_run=true to preview.
Inputs: name (required), confirm, dry_run, workspace.
vector_searchCRead-onlyIdempotent
Semantic search over a vector index. Returns the top_k closest documents.
Inputs: index (required), query (required), top_k, workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to safely call MCP tools through a security gateway that enforces per-role authorization and least-privilege tool scoping.1-
- FlicenseNot gradedqualityCmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceProvides 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 npm1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables external MCP clients to invoke governed tools with schema validation, budgets, policy checks, human approval for side-effecting actions, and prompt-injection quarantine.MIT