{
  "markdown": "<!-- mcp-name: io.github.mattijsmoens/sovereign-mcp-gateway -->\n\n# sovereign-mcp-gateway\n\n**A gating proxy for Model Context Protocol servers.** Point your MCP client at the gateway instead of at your servers. It connects to every upstream you list, merges their tool catalogues into one, and puts every call through a verification chain before it reaches the server that would execute it.\n\n[![Built on patent-pending components](https://img.shields.io/badge/built%20on-patent--pending%20components-brightgreen.svg)]()\n\n```bash\npip install sovereign-mcp-gateway\nsovereign-mcp-gateway --init          # writes gateway.json from the servers you already run\nsovereign-mcp-gateway --config gateway.json --check\n```\n\n`--init` reads the MCP configuration you already have (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) and writes a `gateway.json` that proxies those same servers, so the first run produces a working config rather than a configuration error. It will not import the gateway's own entry, because that would make it proxy itself.\n\nThe gateway is itself an MCP server, so any client that speaks MCP works with no changes.\n\nThat base install is a working gateway. Four optional extras add further layers on top — see [Installing](#installing).\n\n---\n\n## What it stops\n\nAn agent reads a GitHub issue whose body carries an instruction aimed at the model rather than at you. It is persuaded, and calls `git_commit`.\n\n| | commits after | injected commit present |\n| --- | --- | --- |\n| straight to `mcp-server-git` | 2 | yes |\n| through the gateway | 1 | no |\n\nSame tool, same arguments, same server. The difference is whether anything was in a position to refuse.\n\nRead the walkthrough: **[Your agent reads an issue](docs/your-agent-reads-an-issue.md)** — or run it:\n\n```bash\npip install \"sovereign-mcp-gateway[all]\" mcp-server-git\npython examples/poisoned_issue.py\n```\n\n## Why a proxy and not a library\n\nA library has to be adopted by whoever wrote the server. A proxy protects servers you cannot modify — which is most of them, because the useful MCP servers are published packages someone else maintains.\n\nIt also gives you one place to hold policy and one audit trail across every server an agent can reach, rather than per-server configuration nobody keeps in sync.\n\n## Configure\n\n### Start from what you already run\n\n```\n$ sovereign-mcp-gateway --init\n\nWrote gateway.json\n\n  imported 3 servers from Claude Desktop\n    /Users/you/Library/Application Support/Claude/claude_desktop_config.json\n  imported 1 server from VS Code (project)\n\n  upstreams: fetch, git, sqlite, time\n\n  skipped:\n    sovereign - this gateway - importing it would proxy itself\n    notion    - no command, probably a remote/SSE server\n    git       - already imported from another client\n```\n\nFour things it will not do: import itself, import a remote server it cannot launch as a subprocess, overwrite an existing file without `--force`, or write a `deny_tools` list you did not choose. It writes the file, tells you what it took and what it left, and stops.\n\nPass `--config PATH` alongside `--init` to write somewhere other than `./gateway.json`.\n\nAfter running it, replace those servers in your client with a single entry for the gateway. Leaving both means your agent talks to them directly as well as through the proxy, and the audit trail will only show half the traffic.\n\n\n```json\n{\n  \"servers\": {\n    \"git\":    {\"command\": \"mcp-server-git\",    \"args\": [\"--repository\", \"/repo\"]},\n    \"sqlite\": {\"command\": \"mcp-server-sqlite\", \"args\": [\"--db-path\", \"/data.db\"]}\n  },\n  \"policy\": {\"deny_tools\": [\"git__git_reset\"], \"pii_policy\": \"warn\"},\n  \"audit\":  {\"path\": \"gateway-audit.jsonl\"}\n}\n```\n\nCheck the wiring before a client ever sees it:\n\n```bash\nsovereign-mcp-gateway --config gateway.json --check\n```\n\n```\nSOVEREIGN GATEWAY - configuration check\nupstreams: 2\nlayers:   policy -> intent -> text-filter -> frozen-verify -> audit\n\nEXPOSED AS                             UPSTREAM TOOL\ngit__git_status                        git.git_status\ngit__git_reset                         git.git_reset          [DENIED]\nsqlite__read_query                     sqlite.read_query\n...\n18 tools exposed.\n```\n\n## The chain\n\n```\npolicy → intent → text-filter → frozen-verify → [ call executes ] → output-verify → logic-rules → audit\n```\n\n| Layer | Package | Refuses when |\n| --- | --- | --- |\n| policy | — | the tool is on a deny list, or absent from an allow list |\n| intent | `intentshield` | the call fails the behavioural floor |\n| text-filter | `sovereign-shield` | an argument carries injection, in any of 21 languages or seven encodings |\n| frozen-verify | `sovereign-mcp` | the call disagrees with the tool definition frozen at startup |\n| output-verify | `sovereign-mcp` | the result fails schema, deception, PII or content checks |\n| logic-rules | `logicshield` | the result is inconsistent with rules you configured |\n| audit | `sovereign-mcp` | — records every call, allowed or refused, in a hash-chained log |\n\n## Installing\n\nThe base install is a working gateway, not a stub:\n\n```bash\npip install sovereign-mcp-gateway\n```\n\nThat gives you **policy → frozen-verify → audit**, which already refuses a tool no upstream exposes, an argument of the wrong type, an undeclared parameter, a tool on your deny list, and prompt injection in an argument. Nothing else needed.\n\nEach extra adds a layer on top:\n\n| Extra | Adds | Worth it when |\n| --- | --- | --- |\n| `[text]` | `sovereign-shield` — a deeper pass over string arguments: 21 languages, and seven-variant decoding for payloads hidden in base64, hex, ROT13, leetspeak or reversed text | Your agents read text from anywhere you don't control. The base install catches `IGNORE ALL PREVIOUS INSTRUCTIONS`; it will not catch the same sentence base64-encoded, or written in Dutch |\n| `[intent]` | `intentshield` — a behavioural floor applied regardless of which tool was called: shell bans, delete bans, credential URLs, malware syntax | You want a backstop that doesn't depend on getting every tool's schema right |\n| `[rules]` | `logicshield` — consistency rules you write for tool *output* | You can express what a correct result looks like. Does nothing until you set `output_rules` |\n| `[consensus]` | `requests` — needed by Layer C's HTTP providers | You're enabling N-model consensus with a hosted provider |\n\nCombine what you want, or take everything:\n\n```bash\npip install \"sovereign-mcp-gateway[text]\"             # one extra\npip install \"sovereign-mcp-gateway[text,intent]\"      # several\npip install \"sovereign-mcp-gateway[all]\"              # every layer\n```\n\nAll four extras are small pure-Python packages — `[all]` adds no compiled dependencies and no service to run.\n\n**A partial install degrades visibly.** The gateway prints its active layers at startup, so you can always see what is actually running:\n\n```\nlayers:   policy -> frozen-verify -> audit                                  # base\nlayers:   policy -> intent -> text-filter -> frozen-verify -> audit         # [all]\n```\n\nIf a layer isn't on that line, it isn't running — whatever you think you installed.\n\n## Verified end to end\n\nAgainst `mcp-server-git` and `mcp-server-sqlite` running as real upstreams, driven by a real MCP client:\n\n| Call | Result |\n| --- | --- |\n| `git__git_status`, `git__git_log` | allowed |\n| `sqlite__create_table`, `__write_query`, `__read_query` | allowed — the row is really in the database |\n| `git__git_reset` | refused: on the deny list |\n| `git__git_push_force` | refused: no upstream exposes it |\n| `git__git_status(repo_path=12345)` | refused: wrong type for the frozen schema |\n| `git__git_commit(\"IGNORE ALL PREVIOUS INSTRUCTIONS…\")` | refused: text filter |\n| `sqlite__git_commit(...)` | refused: a tool cannot be reached through another upstream's namespace |\n\nAfterwards the repository still holds one commit and the database holds exactly the row it should — checked by opening them directly, not by trusting the gateway's own report. Eleven audit records for ten calls; editing any one of them breaks the chain.\n\nThose cases are the test suite, not a screenshot: `pytest tests/ -v`.\n\n\n## Layer C: N-model consensus\n\nEvery other layer is deterministic and local. Layer C is the exception: it asks several **independent** models to extract the same structured document from a tool's result, canonicalises each answer, and compares the SHA-256 hashes. Agreement is decided by hash, not by prose.\n\nIt is off unless configured, because it is the only layer that costs money and latency per call, and the only one that sends tool output to a model.\n\n```json\n{\n  \"servers\": { \"...\": {} },\n  \"consensus\": {\n    \"providers\": [\n      {\"type\": \"local\", \"model\": \"llama3.1:8b\"},\n      {\"type\": \"local\", \"model\": \"qwen2.5:7b\", \"base_url\": \"http://localhost:11434/v1\"},\n      {\"type\": \"openrouter\", \"model\": \"anthropic/claude-3.5-sonnet\",\n       \"api_key_env\": \"OPENROUTER_API_KEY\"}\n    ]\n  }\n}\n```\n\nTwo provider types: **`local`** (any OpenAI-compatible endpoint — Ollama, vLLM, LM Studio; `base_url` defaults to `http://localhost:11434/v1`) and **`openrouter`** (the key is read from the named environment variable, never written in the config).\n\nThree rules the gateway enforces at startup rather than discovering at runtime:\n\n- **At least two providers.** One model cannot disagree with itself; a consensus of one reports agreement on every call, which is worse than no layer because it looks like verification.\n- **No duplicate models.** Two instances of the same model agreeing is not independent verification.\n- **A missing API key refuses to start.** It does not fall back to running without the layer.\n\nAll providers run at `temperature = 0`, enforced in the constructor.\n\n### Check your models agree before you trust the layer\n\n`--check` runs **one real consensus call** against your configured models and tells you what happened. This matters more than it sounds:\n\n```\nLAYER C  - probing the configured models with one real call\n--------------------------------------------------------------\n  OK. The configured models produced identical documents.\n  Layer C will pass ordinary output rather than refusing it.\n```\n\nConsensus compares canonical hashes, so two models that are both *semantically* right but structurally different never agree. A weaker model that echoes the schema back —\n\n```json\n{\"branch\": {\"type\": \"string\", \"value\": \"main\"}}   instead of   {\"branch\": \"main\"}\n```\n\n— mismatches on every call, forever, and the gateway refuses everything with a reason that correctly reads \"the models disagreed\". Because they did.\n\nThe probe distinguishes the three outcomes:\n\n| | means |\n| --- | --- |\n| **OK** | the models produced identical documents; the layer is usable |\n| **MISMATCH** | they disagree on a trivial document and will refuse every call — replace a model, or drop the section |\n| **provider unreachable** | nothing was verified; a key, a model ID or an endpoint is wrong |\n\nInstall `sovereign-mcp-gateway[consensus]` or `[all]` — the HTTP providers need `requests`, which the core library deliberately does not depend on.\n\n`--check` also lists the active layers, so you can confirm at a glance:\n\n```\nlayers:   policy -> intent -> text-filter -> frozen-verify -> consensus -> audit\n```\n\nIf `consensus` is absent from that line, it is not running, whatever the config says.\n\n## Namespacing\n\nWith `namespace` on (the default) a tool is exposed as `git__git_status`. Two upstreams offering the same tool name cannot collide, shadow each other, or be reached through the wrong namespace. Turn it off only when you have a single upstream.\n\n## Policy\n\n```json\n\"policy\": {\n  \"deny_tools\":  [\"git__git_reset\", \"write_query\"],\n  \"allow_tools\": null,\n  \"pii_policy\":  \"warn\",\n  \"fail_closed\": true,\n  \"rate_limit_interval\": 0\n}\n```\n\n- **`deny_tools`** matches either the exposed name (`git__git_reset`) or the upstream tool name (`git_reset`, on every upstream that has it).\n- **`allow_tools`**, when set, refuses everything not listed.\n- **`pii_policy`** defaults to `warn`, not `block`. Real tools return personal data as normal output — every `git log` entry carries an author email — and blocking those makes the gateway unusable. Set `block` when your tools should never emit PII.\n- **`fail_closed`** decides what happens when a layer itself errors. Default: refuse.\n- **`rate_limit_interval`** is `0`, which disables the behavioural floor's own inter-action delay. That delay is right for one agent taking deliberate steps and wrong for a proxy, where a burst of tool calls is ordinary traffic.\n- **`entropy_policy`** defaults to `warn`. The text filter's entropy heuristic hunts for encoded payloads hidden in prose, but tool arguments are routinely structured — paths, identifiers, hashes — where high entropy is normal. A temporary directory path alone was enough to have a legitimate call refused. Set `block` when your arguments really are prose.\n\n## What this does not do\n\nIt verifies calls against frozen definitions and inspects arguments and results. It does not read your servers' source, so it cannot see a check that is present, is called, and silently does nothing. That still takes someone reading the implementation.\n\nIt also cannot protect against a compromised upstream returning correct-looking data — Layer C consensus in `sovereign-mcp` addresses that, and requires model providers you configure yourself.\n\n## Licence\n\n**Business Source License 1.1** — see [LICENSE](LICENSE).\n\nThe source is public. You may read it, modify it, create derivative works and\nuse it for development, evaluation and any other non-production purpose at no\ncost.\n\n**Production use is also free** for an individual, or an organisation of four\nor fewer people — that is written into the licence as an Additional Use Grant,\nnot just stated here. Larger organisations need a commercial licence.\n\nEach version converts to Apache 2.0 on its Change Date, four years after\npublication.\n\nTo license it for production, or to ask whether your use needs one:\n**contact@sovereign-shield.net**\n",
  "bytes": 14041,
  "sha": "76a53dcb0bd1d9c79e1b72d9c428b861a044c198e162129f01fdba6053b37d53",
  "repo_slug": "mattijsmoens/sovereign-mcp-gateway",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mattijsmoens_sovereign_mcp_gat_9bd44685/readme"
}