Skip to content
Back to search

mcp-secure-gateway

Reproducible MCP server demonstrating scoped tools, deny-by-default authorization and security tests

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wesley-isaias--mcp-secure-gateway/badge.svg)](/listings/wesley-isaias--mcp-secure-gateway)

HTML

<a href="/listings/wesley-isaias--mcp-secure-gateway"><img src="/api/listings/wesley-isaias--mcp-secure-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.

Requires Python 3.11+ on Linux or macOS.

python -m venv .venv && . .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q --cov      # 66 tests, coverage gate 88%
ruff check . && ruff format --check .

Local mode (stdio)

For one operator on their own machine. The role comes from the server's environment.

MCP_DEMO_ROLE=viewer mcp-secure-gateway serve

Network mode (HTTP)

Token file and audit log are mandatory; without them the server exits with an error.

# 1. Create a token. The plaintext is printed once; only its hash goes in the file.
mcp-secure-gateway new-token --client-id ci-bot --role tester
#    -> save the printed JSON entry in tokens.json

# 2. Create an audit key (32+ bytes) readable only by you.
python -c "import secrets; print(secrets.token_hex(32))" > audit.key && chmod 600 audit.key

# 3. Start the server on localhost.
MCP_GATEWAY_TOKENS_FILE=tokens.json \
MCP_GATEWAY_AUDIT_LOG=audit.jsonl \
MCP_GATEWAY_AUDIT_KEY_FILE=audit.key \
mcp-secure-gateway serve --transport http --port 8000

# 4. Verify the audit trail at any time.
mcp-secure-gateway verify-audit audit.jsonl --key-file audit.key
# OK: 12 records, chain intact, last mac 3c9f...

Each call writes a record before it runs and another with its outcome (`succeeded` or `failed`). A record looks like this (no arguments, no results, no client name):

{"client":"0a44aff966f9756b","decision":"allowed","mac":"b10a…","prev":"0000…","reason":"allowed","seq":1,"tool":"run_checks","ts":"2026-11-21T01:12:40.512+00:00"}

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 · 137 lines
  1. # MCP Secure Gateway
  2. [![CI](https://github.com/wesley-isaias/mcp-secure-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/wesley-isaias/mcp-secure-gateway/actions/workflows/ci.yml)
  3. ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.13-blue)
  4. ![Coverage](https://img.shields.io/badge/coverage-94%25%20(CI%20gate%2088%25)-brightgreen)
  5. ![License](https://img.shields.io/badge/license-MIT-green)
  6. A Model Context Protocol (MCP) server that puts every tool call behind one enforcement point: **bearer-token authentication, a deny-by-default policy, per-client rate limiting and a tamper-evident audit log**, all checked before the tool runs.
  7. It is a small, runnable reimplementation of the principles behind [Zayuni DevWS](https://github.com/wesley-isaias/wesley-isaias/blob/main/projects/mcp.md), the MCP server I use in production to give ChatGPT and Claude controlled access to my repositories. No code or configuration from that private system is included. The tools here serve fictional data so that the security layer is the focus.
  8. [Português abaixo](#português)
  9. ## Why
  10. An AI agent connected to tools will eventually receive a malicious or confused instruction. Prompt filtering does not stop that. A gateway that decides **who** is calling, **what** they may do and **records** it before anything happens does. This project shows that layer in about 500 lines of Python, with 66 tests and 94% coverage.
  11. ## How a call flows
  12. ```mermaid
  13. flowchart LR
  14. C[MCP client] -->|Bearer token| A{Token valid?}
  15. A -- no --> X1[401]
  16. A -- yes --> R{Within rate limit?}
  17. R -- no --> X2[denied: rate_limited]
  18. R -- yes --> P{Policy allows role + tool?}
  19. P -- no --> X3[denied: action_denied]
  20. P -- yes --> L[(Audit record<br>written + fsync)]
  21. L -- write failed --> X4[denied: audit_unavailable]
  22. L -- ok --> T[Tool runs]
  23. X2 -.-> L2[(audited)]
  24. X3 -.-> L2
  25. ```
  26. ## Threat model
  27. | Threat | Control | Where it is tested |
  28. | --- | --- | --- |
  29. | Unauthenticated network access | Bearer token required on HTTP; server refuses to start without a token file | `test_http.py::test_request_without_token_gets_401`, `test_server.py::test_http_without_tokens_refuses_to_start` |
  30. | Leaked token file | File stores SHA-256 hashes only; tokens are shown once at creation | `test_tokens_and_ratelimit.py::test_token_file_never_contains_plaintext` |
  31. | Caller escalates its own role | Role comes from the verified token or the operator, never from tool arguments | `test_server.py::test_caller_cannot_escalate_through_arguments` |
  32. | Capability discovery | Tool listings are filtered by role: callers only see tools they may call | `test_server.py::test_tool_list_only_shows_what_the_role_may_call`, `test_http.py::test_viewer_token_does_not_see_tester_tools` |
  33. | Unknown role or tool | Deny by default | `test_policy.py`, `test_server.py::test_unknown_operator_role_denies_everything` |
  34. | Burst abuse | Token bucket per client, bounded memory | `test_tokens_and_ratelimit.py`, `test_server.py::test_rate_limit_blocks_bursts` |
  35. | Silent edits to the audit trail | HMAC-SHA256 chain with sequence numbers; writer refuses to start on a broken chain | `test_audit.py` (edit, delete, reorder, forged record, wrong key) |
  36. | Sensitive data in logs | Closed schema: no arguments, no results; clients pseudonymised with a keyed hash | `test_server.py::test_every_call_is_audited_without_content`, `test_http.py::test_audit_identifies_clients_by_pseudonym_only` |
  37. | Action without a record | Write-ahead audit; if the write fails, the call is denied. A second record stores the outcome | `test_server.py::test_audit_failure_blocks_the_call`, `test_server.py::test_successful_call_records_outcome` |
  38. ## Quick start
  39. Requires Python 3.11+ on Linux or macOS.
  40. ```bash
  41. python -m venv .venv && . .venv/bin/activate
  42. python -m pip install -e ".[dev]"
  43. pytest -q --cov # 66 tests, coverage gate 88%
  44. ruff check . && ruff format --check .
  45. ```
  46. ### Local mode (stdio)
  47. For one operator on their own machine. The role comes from the server's environment.
  48. ```bash
  49. MCP_DEMO_ROLE=viewer mcp-secure-gateway serve
  50. ```
  51. ### Network mode (HTTP)
  52. Token file and audit log are mandatory; without them the server exits with an error.
  53. ```bash
  54. # 1. Create a token. The plaintext is printed once; only its hash goes in the file.
  55. mcp-secure-gateway new-token --client-id ci-bot --role tester
  56. # -> save the printed JSON entry in tokens.json
  57. # 2. Create an audit key (32+ bytes) readable only by you.
  58. python -c "import secrets; print(secrets.token_hex(32))" > audit.key && chmod 600 audit.key
  59. # 3. Start the server on localhost.
  60. MCP_GATEWAY_TOKENS_FILE=tokens.json \
  61. MCP_GATEWAY_AUDIT_LOG=audit.jsonl \
  62. MCP_GATEWAY_AUDIT_KEY_FILE=audit.key \
  63. mcp-secure-gateway serve --transport http --port 8000
  64. # 4. Verify the audit trail at any time.
  65. mcp-secure-gateway verify-audit audit.jsonl --key-file audit.key
  66. # OK: 12 records, chain intact, last mac 3c9f...
  67. ```
  68. Each call writes a record before it runs and another with its outcome (`succeeded` or `failed`). A record looks like this (no arguments, no results, no client name):
  69. ```json
  70. {"client":"0a44aff966f9756b","decision":"allowed","mac":"b10a…","prev":"0000…","reason":"allowed","seq":1,"tool":"run_checks","ts":"2026-11-21T01:12:40.512+00:00"}
  71. ```
  72. ## Tools and roles
  73. | Tool | viewer | tester | Behaviour |
  74. | --- | --- | --- | --- |
  75. | `list_fixtures` | allow | allow | Lists fictional record IDs |
  76. | `get_fixture` | allow | allow | Reads one allow-listed fictional record |
  77. | `run_checks` | deny | allow | Deterministic in-memory checks |
  78. ## Design decisions
  79. - **One enforcement point.** All checks live in `GatewayMiddleware`, including the tool listing; tools contain only business logic, so a new tool cannot forget a check.
  80. - **Write-ahead audit.** The record is flushed with `fsync` before the tool runs. No record means no action.
  81. - **Hashes, not secrets, on disk.** Token file entries are SHA-256 digests, compared without early exit.
  82. - **Fail closed at startup.** Missing token file, missing audit key, malformed entries or a broken audit chain stop the server instead of degrading silently.
  83. - **Small dependency surface.** Security code uses the standard library (`hmac`, `hashlib`, `fcntl`); FastMCP provides the protocol.
  84. ## Limits
  85. - **Tail truncation.** The chain detects edits, deletions, insertions and reordering, but not removal of the last lines. Production systems export periodic checkpoints (last `seq` and `mac`) to write-once storage. Zayuni DevWS does this with an R2 bucket under an indefinite Bucket Lock.
  86. - **Static tokens.** Tokens are long-lived and revoked by removing their hash and restarting. A production deployment would use short-lived OAuth tokens, as Zayuni DevWS does with Cloudflare Access.
  87. - **Single process.** Rate-limit state and the audit writer are per process.
  88. - **Not a sandbox.** The tools here are harmless by design. Real tools that touch files or run commands also need OS-level isolation.
  89. ## License
  90. [MIT](./LICENSE) © 2026 Wesley Isaias
  91. ---
  92. ## Português
  93. Servidor MCP em que toda chamada de ferramenta passa por um único ponto de controle, antes de executar: **autenticação por token, política que nega por padrão, limite de requisições por cliente e log de auditoria à prova de adulteração**.
  94. É uma reimplementação pequena e executável dos princípios do [Zayuni DevWS](https://github.com/wesley-isaias/wesley-isaias/blob/main/projects/pt-br/mcp.md), o servidor MCP que uso em produção para dar ao ChatGPT e ao Claude acesso controlado aos meus repositórios. Nenhum código ou configuração desse sistema privado foi incluído. As ferramentas servem dados fictícios, para que o foco seja a camada de segurança.
  95. - **Instalar e testar:** `python -m pip install -e ".[dev]"`, depois `pytest -q --cov` (66 testes, 94% de cobertura).
  96. - **Modo local (stdio):** `MCP_DEMO_ROLE=viewer mcp-secure-gateway serve`.
  97. - **Modo rede (HTTP):** exige arquivo de tokens (só hashes SHA-256) e log de auditoria; sem eles o servidor não sobe. Veja os passos acima.
  98. - **Verificar a auditoria:** `mcp-secure-gateway verify-audit audit.jsonl --key-file audit.key`.
  99. **Limites:** a cadeia de auditoria não detecta a remoção das últimas linhas sem um checkpoint externo; os tokens são estáticos; o estado é por processo; não é um sandbox de sistema operacional.

Ratings and comments

Sign in to rate this skill.

Sign in

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