mcpgate: auth gateway for self-hosted MCP servers

The gateway is set up and tested against your filesystem server: Claude Code gets the 9 read tools only, and the CI bot gets all 13. Before writing the allowlists I pulled the exact tool names from your server with scripts/discover_tools.py, because mcpgate matches tool names exactly and a guessed name (like read_file) would quietly block a tool.

client --Bearer key--> mcpgate 127.0.0.1:8080 --> filesystem MCP 127.0.0.1:9000/mcp
                         auth -> rate limit -> tool allowlist -> proxy
                         one JSON audit line per request -> ./mcpgate-audit.jsonl

What your server exposes (13 tools)

Your server has no delete tool. Removing or renaming a file goes through move_file or an overwrite through write_file/edit_file, and Claude Code is blocked from all of them.

1. Install and mint keys

bash scripts/install.sh              # checksum-verified release binary -> ~/.local/bin
mcpgate keygen --label claude-code   # prints the key once + a config entry with its SHA-256 hash
mcpgate keygen --label ci-bot

Treat the printed keys like passwords: only their hashes go in config.yaml. Put the CI key in your CI secret store.

2. config.yaml

upstream:
  url: "http://127.0.0.1:9000/mcp"
  timeout: 30s

listen: "127.0.0.1:8080"   # localhost only. Put TLS in front before exposing it to a network.

keys:

  # Claude Code: read-only. Write/edit/move/create tools are denied AND hidden from tools/list.
  - label: "claude-code"
    hash: "<sha256 from mcpgate keygen>"
    allow:
      - read_text_file
      - read_media_file
      - read_multiple_files
      - list_directory
      - list_directory_with_sizes
      - directory_tree
      - search_files
      - get_file_info
      - list_allowed_directories
    rate_limit: { rps: 5, burst: 20 }   # a client's connect sequence can exhaust burst 5 -> 429

  # CI bot: every tool, including any the upstream adds later.
  - label: "ci-bot"
    hash: "<sha256 from mcpgate keygen>"
    allow: ["*"]
    rate_limit: { rps: 10, burst: 30 }

audit:
  output: "./mcpgate-audit.jsonl"

• CI bot gets "*": that also covers tools the server adds later. To review each new tool first, list the 13 names instead.
• Keep the file out of git: add config.yaml to .gitignore.

3. Run it

mcpgate validate -c config.yaml   # -> OK: 2 key(s), upstream http://127.0.0.1:9000/mcp
mcpgate serve -c config.yaml      # -> mcpgate listening on 127.0.0.1:8080 -> http://127.0.0.1:9000/mcp

mcpgate doesn't hot-reload, so restart serve after every config change. Want a launchd plist, systemd unit or docker run --restart unless-stopped to keep it running? Tell me which.

4. Connect Claude Code

export MCPGATE_KEY='mcpg_...'   # the claude-code key, e.g. in ~/.zshrc
claude mcp add --transport http files http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $MCPGATE_KEY"

For a shared project .mcp.json, reference the variable so each person uses their own key:

{ "mcpServers": { "files": { "type": "http", "url": "http://127.0.0.1:8080/mcp",
  "headers": { "Authorization": "Bearer ${MCPGATE_KEY}" } } } }

If Claude Code is currently connected straight to :9000, remove that entry, or it can go around the gateway.

Test results

I ran your config on a scratch port against your upstream, then stopped it:

The audit log recorded each request under the right label:

{"label":"claude-code","method":"tools/call","tool":"write_file","decision":"deny:policy","status":200,...}
{"label":"ci-bot","method":"tools/call","tool":"write_file","decision":"allow","status":200,...}

To review later: python3 scripts/audit_summary.py mcpgate-audit.jsonl --label ci-bot --since 1d.

Limits worth knowing

Only tools are checked. Resources and prompts pass through for any valid key; the filesystem server's actions are all tools, so that doesn't matter here.

• Revoking a key: remove or replace its entry and restart. The old key keeps working until the restart.