# Enterprise MCP Gateway

**Secure AI-to-business tool infrastructure built on the Model Context Protocol.**

A production-oriented MCP gateway that lets an AI agent work with CRM, order,
support and automation systems — with authentication, RBAC, a policy engine,
prompt-injection defences, audit logging, rate limiting, idempotency,
observability, n8n integration and a remote Streamable HTTP transport.

> Status: **under active construction.** `docs/implementation-status.md` records
> exactly which phases are complete and verified. Nothing is claimed here that
> has not been executed.

---

## What MCP is, in one paragraph

The Model Context Protocol is an open protocol that lets an AI host discover and
call capabilities exposed by a server: **tools** (actions and queries),
**resources** (authoritative read-only context) and **prompts** (reusable,
parameterised instructions). It standardises the wire format so any compliant
host can talk to any compliant server. What it deliberately does *not* do is
decide who is allowed to call what — that is the server's job, and that is what
this project is about.

## What this project solves

Connecting an LLM to real business systems is not a tooling problem, it is a
**trust boundary** problem. A naive MCP server hands an agent unmediated access
to production data. This gateway inserts the layer a company actually needs:

- the caller's identity comes from a verified bearer token, never from a tool
  argument;
- every tool declares its required permission, risk level and audit class in one
  authoritative registry, and the server enforces it before any business code
  runs;
- high-risk actions (sending customer email, triggering automations) require
  explicit confirmation and are idempotent;
- customer-authored text is treated as untrusted data and is labelled as such
  when it reaches the model, so "ignore your instructions" in a ticket body is
  just a string;
- every consequential operation lands in an append-only audit trail.

## Architecture

```
AI Host / Agent  →  MCP Client  →  Enterprise MCP Gateway  →  Business systems

                    observability → audit → authn → authz →
                    rate limit → policy → idempotency → tool handler
                                                          ↓
                                                application services
                                                          ↓
                                     PostgreSQL · Redis · n8n · email adapter
```

Full detail, sequence diagrams and trust boundaries: **[docs/architecture.md](docs/architecture.md)**.

## Technology

| Layer | Choice |
|---|---|
| Runtime | Python 3.12+ (developed on 3.14.3) |
| MCP | Official Python SDK `mcp==2.1.1` (v2 API: `MCPServer`, `ServerMiddleware`) |
| Transports | `stdio` (local) and Streamable HTTP (remote) |
| Data | PostgreSQL via SQLAlchemy 2 + Alembic |
| Cache / limits | Redis |
| Automation | n8n |
| Auth | OIDC/JWT (JWKS), with a separated development mode |
| Observability | structlog + OpenTelemetry |

Rationale for each choice, including what was rejected:
**[docs/technology-decisions.md](docs/technology-decisions.md)**.

## Documentation

| Document | Contents |
|---|---|
| [architecture.md](docs/architecture.md) | Layering, middleware pipeline, sequences, trust boundaries |
| [technology-decisions.md](docs/technology-decisions.md) | Stack choices and rejected alternatives |
| [implementation-status.md](docs/implementation-status.md) | Per-phase status, tests run, known limitations |

Security, tool catalogue, deployment, threat model and the demo script are added
in their corresponding phases.

## Licence

MIT — see [LICENSE](LICENSE).