# MCP Gateway Core

A **Capability Execution Platform** -- not an AI framework, not an agent,
not an MCP protocol implementation. It is the foundation layer a future
Enterprise AI Platform sits on top of: a dynamic, database-driven registry
of named **capabilities** (`customer.create`, `invoice.approve`,
`knowledge.search`, ...) that can be executed on demand and routed to
whichever backend system actually performs the work.

Any system can call it: Agno, Claude, OpenAI-based agents, LangGraph,
CrewAI, n8n, an ERP, a CRM, or a person testing via Swagger. The gateway
itself never hardcodes a single capability, workflow, or business rule --
everything is metadata loaded from PostgreSQL at request time.

## Why this exists

Most "AI + automation" stacks end up wiring every agent framework directly
to every backend system, which means N frameworks x M systems integration
points, all duplicating auth, validation, retries, and audit logging. This
gateway collapses that to N + M: every caller talks to one gateway using
one contract (`POST /api/v1/execute`), and every backend system is
integrated exactly once as a **provider**.

## Core concepts

A **capability** is metadata describing something that can be executed --
a code (`customer.create`), a provider type (`http`, `n8n`, `mock`, ...),
an endpoint, and JSON input/output schemas. It carries no logic itself.

A **provider** is the strategy that actually executes a capability:
`HttpProvider` calls a REST endpoint, `N8NProvider` triggers an n8n
webhook, `MockProvider` echoes back the payload for testing. New provider
types are added by implementing one interface -- the dispatcher and API
never change.

The **dispatcher** is the orchestrator: given a capability code, a
payload, and caller context, it loads the capability, checks it is
enabled, resolves the right provider, executes it, writes an audit log,
and returns a standardized response -- regardless of what actually ran
underneath.

See [`docs/Architecture.md`](docs/Architecture.md) for the full design
rationale, [`docs/API.md`](docs/API.md) for the REST contract, and
[`docs/Development.md`](docs/Development.md) for local setup.

## Tech stack

Python 3.12, FastAPI, PostgreSQL with SQLAlchemy 2.0 (async) and Alembic
migrations, Redis as an optional read-through cache, Pydantic v2 for
validation, Docker / Docker Compose for local orchestration, Pytest for
testing.

## Quick start

```bash
git clone <repo-url> mcp-gateway-core
cd mcp-gateway-core
cp .env.example .env
docker compose up --build
```

This starts PostgreSQL, Redis, and the gateway; runs migrations; seeds
four sample capabilities (`customer.create`, `customer.search`,
`invoice.approve`, `mock.echo`); and serves the API at
`http://localhost:8000`. Interactive docs live at
`http://localhost:8000/docs`.

Try the safe-to-call sample capability:

```bash
curl -X POST http://localhost:8000/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"capability": "mock.echo", "payload": {"hello": "world"}, "context": {"userId": "u1"}}'
```

For the step-by-step local (non-Docker) workflow -- virtualenv, running
Alembic by hand, running the test suite -- see
[`docs/Development.md`](docs/Development.md).

## Project layout

```
app/
  api/             FastAPI routers + Pydantic schemas (capabilities, execution, health)
  domain/          Framework-free entities, value objects, exceptions, the Provider interface
  application/     Use-case services: registry, dispatcher, execution, audit
  infrastructure/  SQLAlchemy models, repositories, Redis client, concrete providers
  core/            Settings, structured logging, DI wiring, error handlers
migrations/        Alembic environment + versioned schema migrations
scripts/           Seed script for sample capabilities
tests/             unit / integration / repository test suites
docker/            Auxiliary container assets (Dockerfile + compose live at repo root)
docs/              Architecture, Development, API reference
```

## MCP bridge (SSE)

The `mcp_server/` package turns the Gateway into a real **MCP server**,
serving over SSE on port 8100. Every enabled capability in the registry
appears as a named MCP tool. Any MCP-speaking AI client can connect:

| Client | Config |
|---|---|
| **n8n MCP Client Tool** | SSE URL → `http://<host>:8100/sse` |
| **Claude Desktop** | use `npx mcp-remote http://<host>:8100/sse` |
| **Claude.ai remote** | Project → MCP Connectors → `http://<host>:8100/sse` |
| **OpenAI Agents SDK** | `MCPServerSse(url="http://<host>:8100/sse")` |
| **LangGraph / custom** | `mcp.client.sse.sse_client("http://<host>:8100/sse")` |

Run it alongside the Gateway with `docker compose up --build` (the bridge
is included as the `mcp-server` service). See [`docs/MCP.md`](docs/MCP.md)
for the full guide including n8n workflow integration.


## Status

This is a v0.1 reference implementation of the gateway core: capability
registry, dispatcher, three provider strategies (mock/http/n8n), audit
logging, and observability endpoints are implemented and tested. Things
intentionally left for a follow-up iteration: authentication/authorization
on the registry and execute APIs, per-capability rate limiting, request
payload validation against `input_schema`, and a provider-config-driven
(rather than env-var-driven) n8n/HTTP connection setup.