Skip to content
Back to search

mcp-policy-gateway

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vivshanbhag--mcp-policy-gateway/badge.svg)](/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.jsonl

Create 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
  1. # MCP Policy Gateway
  2. 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.
  3. 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?*
  4. ```
  5. ┌────────────┐ JSON-RPC over stdio ┌──────────────────────────────┐
  6. │ MCP host │ ──────────────────────▶ │ mcp-policy-gateway │
  7. │ (agent) │ ◀────────────────────── │ protocol → policy → schema │
  8. └────────────┘ │ → timeout → audit → tool │
  9. └───────────────┬──────────────┘
  10. │
  11. ┌───────▼────────┐
  12. │ SQLite │
  13. │ jobs, events │
  14. └────────────────┘
  15. ```
  16. ## Why this exists
  17. Giving an agent a `run_shell` tool is easy. Making that safe and operable is the hard part:
  18. | Risk | Control in this repo |
  19. | --- | --- |
  20. | Agent invents arguments | Closed JSON Schema, validated before the handler |
  21. | Agent retries a write and duplicates work | Required `idempotency_key`, unique index, duplicate detection |
  22. | Prompt-injected agent calls tools it shouldn't | Per-caller scopes; `tools/list` only advertises what the caller may use |
  23. | Runaway loop hammers a downstream system | Per-principal, per-tool token bucket |
  24. | Hung backend blocks the session | Per-tool execution budget, reported as a tool error |
  25. | Nobody can explain what happened | Append-only JSONL audit with secret redaction |
  26. ## Quick start
  27. No dependencies, Python 3.11+.
  28. ```bash
  29. git clone https://github.com/vivshanbhag/mcp-policy-gateway
  30. cd mcp-policy-gateway
  31. # Talk to it over stdio, exactly like an MCP host would.
  32. printf '%s\n' \
  33. '{"jsonrpc":"2.0","id":1,"method":"server/discover"}' \
  34. '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' \
  35. | PYTHONPATH=src python3 -m mcp_gateway --db /tmp/demo.db --audit /tmp/audit.jsonl
  36. ```
  37. Create a job:
  38. ```json
  39. {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  40. "name":"scheduler_create_job",
  41. "arguments":{
  42. "name":"nightly-compaction",
  43. "schedule":"0 2 * * *",
  44. "command":"python -m compaction --full",
  45. "idempotency_key":"2026-07-28/nightly-compaction"
  46. },
  47. "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}
  48. }}
  49. ```
  50. Send it twice: the second call returns the same `job_id` with `"duplicate": true` and creates nothing.
  51. ## Protocol support
  52. 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:
  53. - **Modern era** — `server/discover`, per-request `_meta` version, no session state.
  54. - **Legacy era** — `initialize` → `notifications/initialized` → normal requests.
  55. An unknown version gets `-32022 Unsupported protocol version` with the supported list, as the spec requires.
  56. ## Tools
  57. | Tool | Scope | Mutating | Notes |
  58. | --- | --- | --- | --- |
  59. | `scheduler_create_job` | `scheduler:write` | yes | Requires `idempotency_key`; supports `dry_run` |
  60. | `scheduler_list_jobs` | `scheduler:read` | no | Filter by status, capped limit |
  61. | `scheduler_cancel_job` | `scheduler:write` | yes | Cancelling twice is reported, not an error |
  62. | `scheduler_job_history` | `scheduler:read` | no | Event trail per job |
  63. ## Callers and scopes
  64. On stdio there is no bearer token, so the host passes the caller in `_meta`:
  65. ```json
  66. "_meta": {
  67. "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  68. "io.modelcontextprotocol/principal": {"name": "analyst", "scopes": ["scheduler:read"]}
  69. }
  70. ```
  71. 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`.
  72. ## Tests
  73. ```bash
  74. PYTHONPATH=src python3 -m unittest discover -s tests -v
  75. ```
  76. 18 tests cover both protocol eras, scope filtering, idempotency, dry runs, argument rejection, rate limiting, timeouts, cancellation, audit records, and redaction.
  77. ## Design documents
  78. - [`docs/HLD.md`](docs/HLD.md) — context, trust boundaries, request lifecycle, failure modes, deployment.
  79. - [`docs/LLD.md`](docs/LLD.md) — module contracts, data model, error taxonomy, sequence diagrams, extension guide.
  80. ## Limitations
  81. - stdio transport only; HTTP would need the MCP authorization flow.
  82. - SQLite is a single-process store; multi-replica deployment needs a shared database and a distributed rate limiter.
  83. - Timeouts are cooperative: the future is abandoned, not the underlying thread.
  84. - 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 in

Free to use. If it’s helped, pass it on.