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.

Related MCP server: Enterprise MCP Gateway and Tool Registry

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 for the full design rationale, docs/API.md for the REST contract, and 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

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:

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.

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:

Run it alongside the Gateway with docker compose up --build (the bridge is included as the mcp-server service). See 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.