Back to search
mcp-policy-gateway
MCP serverGitHub
Dual-era MCP server with caller scopes, per-tool rate limits, idempotency and a redacted audit trail in front of a job scheduler
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/vivshanbhag--mcp-policy-gateway)HTML
<a href="/listings/vivshanbhag--mcp-policy-gateway"><img src="/api/listings/vivshanbhag--mcp-policy-gateway/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
No dependencies, Python 3.11+.
git clone https://github.com/vivshanbhag/mcp-policy-gateway
cd mcp-policy-gateway
# Talk to it over stdio, exactly like an MCP host would.
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"server/discover"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' \
| PYTHONPATH=src python3 -m mcp_gateway --db /tmp/demo.db --audit /tmp/audit.jsonlCreate a job:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
"name":"scheduler_create_job",
"arguments":{
"name":"nightly-compaction",
"schedule":"0 2 * * *",
"command":"python -m compaction --full",
"idempotency_key":"2026-07-28/nightly-compaction"
},
"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}
}}Send it twice: the second call returns the same `job_id` with `"duplicate": true` and creates nothing.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 114 lines
- # MCP Policy Gateway
- A Model Context Protocol server that puts **scopes, rate limits, argument validation, idempotency, and an audit trail** in front of a real internal system — a persistent job scheduler — instead of exposing it raw to a model.
- Most MCP examples are a thin wrapper over an API. This one treats the model as an untrusted caller and answers the questions a production team actually asks: *who called this, were they allowed, did it run twice, what did it cost, and can I prove it afterwards?*
- ```
- ┌────────────┐ JSON-RPC over stdio ┌──────────────────────────────┐
- │ MCP host │ ──────────────────────▶ │ mcp-policy-gateway │
- │ (agent) │ ◀────────────────────── │ protocol → policy → schema │
- └────────────┘ │ → timeout → audit → tool │
- └───────────────┬──────────────┘
- │
- ┌───────▼────────┐
- │ SQLite │
- │ jobs, events │
- └────────────────┘
- ```
- ## Why this exists
- Giving an agent a `run_shell` tool is easy. Making that safe and operable is the hard part:
- | Risk | Control in this repo |
- | --- | --- |
- | Agent invents arguments | Closed JSON Schema, validated before the handler |
- | Agent retries a write and duplicates work | Required `idempotency_key`, unique index, duplicate detection |
- | Prompt-injected agent calls tools it shouldn't | Per-caller scopes; `tools/list` only advertises what the caller may use |
- | Runaway loop hammers a downstream system | Per-principal, per-tool token bucket |
- | Hung backend blocks the session | Per-tool execution budget, reported as a tool error |
- | Nobody can explain what happened | Append-only JSONL audit with secret redaction |
- ## Quick start
- No dependencies, Python 3.11+.
- ```bash
- git clone https://github.com/vivshanbhag/mcp-policy-gateway
- cd mcp-policy-gateway
- # Talk to it over stdio, exactly like an MCP host would.
- printf '%s\n' \
- '{"jsonrpc":"2.0","id":1,"method":"server/discover"}' \
- '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' \
- | PYTHONPATH=src python3 -m mcp_gateway --db /tmp/demo.db --audit /tmp/audit.jsonl
- ```
- Create a job:
- ```json
- {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
- "name":"scheduler_create_job",
- "arguments":{
- "name":"nightly-compaction",
- "schedule":"0 2 * * *",
- "command":"python -m compaction --full",
- "idempotency_key":"2026-07-28/nightly-compaction"
- },
- "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}
- }}
- ```
- Send it twice: the second call returns the same `job_id` with `"duplicate": true` and creates nothing.
- ## Protocol support
- The 2026-07-28 revision removed the `initialize` handshake — every request now carries its protocol version in `_meta`. Older hosts still handshake. This server speaks both:
- - **Modern era** — `server/discover`, per-request `_meta` version, no session state.
- - **Legacy era** — `initialize` → `notifications/initialized` → normal requests.
- An unknown version gets `-32022 Unsupported protocol version` with the supported list, as the spec requires.
- ## Tools
- | Tool | Scope | Mutating | Notes |
- | --- | --- | --- | --- |
- | `scheduler_create_job` | `scheduler:write` | yes | Requires `idempotency_key`; supports `dry_run` |
- | `scheduler_list_jobs` | `scheduler:read` | no | Filter by status, capped limit |
- | `scheduler_cancel_job` | `scheduler:write` | yes | Cancelling twice is reported, not an error |
- | `scheduler_job_history` | `scheduler:read` | no | Event trail per job |
- ## Callers and scopes
- On stdio there is no bearer token, so the host passes the caller in `_meta`:
- ```json
- "_meta": {
- "io.modelcontextprotocol/protocolVersion": "2026-07-28",
- "io.modelcontextprotocol/principal": {"name": "analyst", "scopes": ["scheduler:read"]}
- }
- ```
- If it is absent, the process principal (`--principal` / `--scopes`) is used. This trust model is deliberate and documented: stdio runs inside the host's process tree, so the host is already trusted. On HTTP the principal must come from the validated token instead — see `docs/HLD.md`.
- ## Tests
- ```bash
- PYTHONPATH=src python3 -m unittest discover -s tests -v
- ```
- 18 tests cover both protocol eras, scope filtering, idempotency, dry runs, argument rejection, rate limiting, timeouts, cancellation, audit records, and redaction.
- ## Design documents
- - [`docs/HLD.md`](docs/HLD.md) — context, trust boundaries, request lifecycle, failure modes, deployment.
- - [`docs/LLD.md`](docs/LLD.md) — module contracts, data model, error taxonomy, sequence diagrams, extension guide.
- ## Limitations
- - stdio transport only; HTTP would need the MCP authorization flow.
- - SQLite is a single-process store; multi-replica deployment needs a shared database and a distributed rate limiter.
- - Timeouts are cooperative: the future is abandoned, not the underlying thread.
- - The scheduler stores job definitions and events; it does not execute the jobs. That boundary is intentional so the gateway stays testable.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.