# 🔐 mcp-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

```bash
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.

```python
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
```bash
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`)