Tool Gateway

A secure tool-execution plane for agentic AI — an MCP-style tool server fronted by a gateway that enforces identity (JWT + scopes), quota (token-bucket rate limiting), and safety (prompt-injection inspection), ingests downstream APIs from OpenAPI, and writes a structured audit log. Pure Python, zero dependencies.

Mirrors the secure agent tool-execution plane I run in production (MCP / OpenAPI behind API governance, JWT validation, Entra-style scope propagation, and prompt inspection) — the controls that let agentic systems clear banking compliance audits.

Request lifecycle

 agent tool call ─▶ ┌──────────────────────── SecureToolGateway ───────────────────────┐
   (+ JWT)          │ 1 authenticate (HS256 verify, exp)                                │
                    │ 2 rate limit  (per-principal token bucket)                        │
                    │ 3 authorize   (tool.required_scope ∈ principal.scopes)            │
                    │ 4 inspect IN  (prompt-injection / exfiltration / cmd-injection)   │
                    │ 5 execute     (MCP server: tools/list · tools/call)               │
                    │ 6 inspect OUT + audit log                                         │
                    └──────────────────────────────────────────────────────────────────┘

Components

Module	Responsibility
jwt_auth	HS256 JWT encode/verify (from scratch), exp check, Principal with scope helpers
rate_limit	TokenBucket + per-principal RateLimiter
inspection	Rule-based Inspector (instruction-override, exfiltration, command-injection, role-spoofing) with severity-based blocking
mcp	MCPServer implementing tools/list and tools/call over JSON-RPC
openapi	tools_from_openapi — auto-register downstream API operations as MCP tools
audit	Append-only structured AuditLog
gateway	SecureToolGateway wiring auth → quota → authz → inspection → execute → audit

Quickstart

python examples/run_gateway.py

Output demonstrates: an authorized call, a missing-scope rejection, a blocked prompt-injection payload, an invalid token, and the populated audit trail.

from mcp_gateway import MCPServer, MCPTool, SecureToolGateway, encode

server = MCPServer()
server.register(MCPTool("get_trade_status", "...", schema,
                        handler=lambda trade_id: "ACK", required_scope="trades:read"))
gw = SecureToolGateway(server=server, secret="...")

token = encode({"sub": "agent-1", "scopes": ["trades:read"]}, "...")
gw.handle({"id": 1, "method": "tools/call",
           "params": {"name": "get_trade_status", "arguments": {"trade_id": "T-1"}}}, token)

Security properties

• Fail-closed: missing scope, bad signature, expired token, or a high-severity finding all reject before the tool ever executes.
• Defense in depth: inputs and outputs are inspected; everything is audited.
• Least privilege: per-tool required_scope, per-principal quota.

Tests

pip install pytest && pytest -q

Covers JWT round-trip + tamper detection, scope enforcement, injection blocking, rate limiting, and inspector severity.

Tech

Python 3.10+ · stdlib only (optional: pytest)