MCP Gateway Registry

Unified Agent & MCP Server Registry – Gateway for AI Development Tools

Get Running Now | Docs | Executive Brief | Slide Deck | Demo Videos | AWS Workshop | Community

---

The MCP Gateway & Registry is a single, governed control plane for every AI asset in your organization, from MCP servers and AI agents to skills and any custom asset your teams build. It is open source, licensed under Apache 2.0, and runs on Kubernetes (Amazon EKS), fully managed serverless (Amazon ECS), or Docker Compose (Amazon EC2).

It began as a gateway and registry for the Model Context Protocol (MCP): one secure entry point to many MCP servers, with centralized discovery and governance. As teams started registering agents, skills, and other assets alongside their servers, it grew into a general-purpose AI asset registry on the same gateway, access-control, and audit model it started with.

Why we built this

Without a control plane, every team wires its own MCP servers and agents by hand: separate credentials in every dotfile, no shared inventory, no audit trail, and no way to discover or govern what exists. Agents can't find other agents; servers and agents live in separate registries that can't share policy.

This platform replaces that with one governed entry point for every AI asset. Register a server, agent, skill, or custom entity once; discover it by natural-language search; reach it through a single authenticated gateway that enforces access and records every call. One control plane, one access model, one audit trail, across all asset types.

Onboard third-party OAuth MCP servers, the enterprise way. Because the gateway provides per-user egress authentication, you can connect OAuth-protected SaaS MCP servers such as Slack, Atlassian, and GitHub without every user setting up network access to those services or storing credentials on their laptop. Each user connects their account once; the gateway runs the OAuth (3LO) flow, vaults the per-user token in a secrets manager, and injects it on egress. That collapses onboarding to a single, auditable choke point, so a team can adopt a new SaaS MCP server across the enterprise without per-laptop plumbing or scattered long-lived tokens.

How it works

The gateway is the data plane (a generic nginx reverse proxy: TLS, auth validation, routing to backends) and the registry is the control plane (a FastAPI service that owns the inventory, access model, and audit trail, and decides what the gateway may route to). An auth server integrates your identity provider (Keycloak, Entra ID, Okta, Auth0, Cognito, PingFederate) for OAuth2/OIDC, and MongoDB / DocumentDB stores configuration, embeddings, sessions, and audit records.

By default, the registry handles A2A discovery, authentication, and access control, and agents then communicate directly (peer-to-peer) rather than routing every call through the gateway. For the full design and its invariants, read the Theory of the System; for layered diagrams, see Architecture Diagrams.

See it in action

Watch how MCP servers, A2A agents, and external registries work together for dynamic tool discovery:

https://github.com/user-attachments/assets/97c640db-f78b-4a6c-9662-894f975f66e2

More walkthroughs are in the demo videos.

Start here if you are a...

You are a...	Start here
Developer	Start with the Complete Setup Guide; you can also try the macOS setup skill to get it running on your MacBook. Then connect your AI coding assistant with the AI Coding Assistant Integration guide. For programmatic access, see the OpenAPI spec plus a Python registration client (registry_client.py) and CLI (registry_management.py).
Platform / security / ops team	See the deployment guides for Amazon EKS (Helm), Amazon ECS (Terraform), and Docker Compose; the authentication guide; the configuration reference; and access control & scopes.
Decision-maker evaluating adoption	Read the Executive Brief, watch the demo videos, and try the AWS Workshop.

Quick Start

The fastest path is the pre-built Docker images. Clone, set a few secrets, and run:

git clone https://github.com/agentic-community/mcp-gateway-registry.git
cd mcp-gateway-registry
cp .env.example .env

# Edit .env and set the required secrets (e.g. KEYCLOAK_ADMIN_PASSWORD, SECRET_KEY).
# See docs/configuration.md for the full list.
nano .env

# Deploy with pre-built images (pulled from Amazon ECR Public by default)
./build_and_run.sh --prebuilt

# Open the Registry UI (served by nginx on port 80)
open http://localhost        # macOS  (Linux: xdg-open http://localhost)

The Complete Installation Guide has the full walkthrough for Amazon EC2 (prerequisites, MongoDB and Keycloak initialization, first user and service account, registering a server, and testing the gateway).

Deploying somewhere else?

• Amazon ECS: see the Terraform stack README, or better, use the Terraform setup skill to have your AI coding assistant run the deployment for you.
• Amazon EKS: see the Helm charts.
• Just want to try it on macOS?: use the macOS setup skill to get it running on your MacBook end to end.

What's in the box

The registry holds four built-in asset types plus admin-defined custom ones, all on one control plane:

• MCP servers: register, discover, and govern access to MCP servers behind a single authenticated gateway.
• Agents (A2A): register agents and let them discover each other by capability; by default agent-to-agent traffic runs peer-to-peer.
• Skills: register, version, and discover reusable SKILL.md skills, with security scanning at registration.
• Custom entities: admins define their own schema-driven entity types (n8n workflows, policies, prompt templates, model cards, and more); see Custom Entity Types.

Across all of them you get semantic + lexical search, UI, REST, and MCP-native interfaces, and uniform governance. Key features worth calling out:

• Use it as an AI gateway for anything HTTP: one authenticated entry point in front of model inference (OpenAI, Amazon Bedrock, any OpenAI-compatible endpoint), MCP servers, A2A agents, and any generic REST endpoint. Callers hold a gateway token; the backend URL and its credential stay in the registry, encrypted at rest and injected at egress, with per-entity streaming and the same scopes, audit, and rate limits as everything else. Off by default. Design · FAQ: OpenAI and Bedrock
• Single authenticated gateway: one entry point; OAuth against your existing IdP (Keycloak, Entra ID, Okta, Auth0, Cognito, PingFederate) with fine-grained scopes.
• Dynamic tool discovery: agents and coding assistants find tools at runtime by natural-language semantic search, not hard-coded config.
• Virtual MCP servers: aggregate tools from many backends behind one endpoint, with per-tool access control.
• Per-user egress auth (3LO / OBO / PAT): the gateway brokers third-party SaaS credentials so tokens never live on a user's laptop.
• Security scanning + fail-closed admission gate: every registered server, agent, and skill is scanned; unsafe items are held for review.
• External-registry federation: pull in Anthropic's MCP Registry, AWS Agent Registry, and peer registries for one unified surface.
• Audit logging: a full, attributable audit trail of access and admin events, with credential masking, for compliance and incident review.
• Observability: OpenTelemetry metrics and health monitoring built in.

What's New

• MCP 2026-07-28 Support - The gateway serves MCP 2026-07-28 clients, which send no initialize and no session id, and clients of earlier revisions on the same URLs. Virtual servers answer server/discover and bridge a 2026-07-28 client to handshake-era backends, and nginx rejects a request whose Mcp-Method or Mcp-Name header disagrees with its body. Tool discovery, the health check, the security scanner and mcpgw move to MCP SDK 2.x. A scope with tools: ["*"] now grants tools only, so check custom scopes that relied on it for other methods before upgrading. See the 1.37.0 release notes and MCP 2026-07-28 support.
• Pooled mcpgw Connections, Calling Tools Found by Search, and an Opt-In OBO Token Cache - mcpgw keeps one pooled HTTP client for its registry and token traffic instead of opening a new connection for every tool call, with its own copy of the registry's egress guard, and the registry and auth-server pools now use their configured 30-second keep-alive instead of the httpx default of 5. An agent that finds a tool with search_registry can call it right away: coding agents get curl steps in mcpgw's instructions, and applications get a helper that calls the tool through the gateway as the user, with the application keeping the token. The auth server can now cache exchanged on-behalf-of tokens per user and audience for up to five minutes, off by default. NGINX_DISABLE_API_AUTH_REQUEST=true works again, so remove it unless you want cookie-only /api/. See the 1.36.0 release notes and the OBO token cache guide.
• Keycloak OBO Token Exchange, Users in Many Groups, and Bounded Registrant Metadata - Egress on-behalf-of now works with Keycloak: the auth server exchanges the user's token for one scoped to the target client (RFC 8693), verifies it, and refuses it if the gateway itself would accept it, so the upstream cannot replay it against the gateway. Users in about 180 or more IdP groups no longer get a 500 from registry API calls, because groups now cross nginx once inside the signed token and the auth subrequest has room for them. The Helm stack chart now owns keycloak-client-secret, so ArgoCD can sync it; existing installs adopt the Secret once before upgrading. Registrant metadata is capped at 10 KB and 8 levels, and the mcpgw discovery tools return it only when a caller names the keys it wants. See the 1.35.0 release notes, which list four breaking changes and the Helm adoption commands.
• Embeddings Without LiteLLM, Extra Request Headers, and Long Entries That Get Indexed - Remote embeddings no longer go through LiteLLM: the registry calls OpenAI and any OpenAI-compatible endpoint, Azure OpenAI, and Amazon Titan and Cohere on Amazon Bedrock with about 500 lines of its own code, sends the same requests so stored vectors stay valid, and rejects a model name it cannot serve at startup instead of on the first call. Operators can add up to five headers to every embeddings request for an endpoint behind an API gateway, and set the request timeout and retry count. An entry whose text is longer than the model accepts, typically a server with many tools, used to stay out of semantic search; the registry now retries a failed embedding once with the longest tool descriptions shortened and every name kept. Entra deployments now recover group memberships from Microsoft Graph when a token omits them. Every image we build also drops the two root CAs distrusted on 2026-10-20. See embeddings and the 1.34.0 release notes, which list the three model-name forms that now stop startup.
• Virtual-Server Credential Brokering and Root-Endpoint Routing - A virtual MCP server can now front a backing server that needs a per-user credential: the backend hop goes through the same vend-and-inject step a direct call uses, keyed on the resolved backing path, so two backing servers with different credential modes can sit behind one virtual server and each gets its own vend. The caller must hold a grant on both the virtual server and the backing server, checked against the exact rewritten request, and the caller's own gateway token is never forwarded to a registrant-controlled backend. The same change lets a virtual server front a stateless Streamable HTTP backend. Separately, a server registered with append_mcp_path: false is now reachable at the bare path it advertises, instead of only the trailing-slash form MCP clients refuse to follow a redirect to. 1.33.0 release notes Older highlights → Feature & Release Highlights · full per-version detail in the release notes and on the GitHub Releases page.

Roadmap

The roadmap is best tracked on the GitHub Milestones page. Per-user egress auth (3LO and OBO) and A2A traffic routing shipped in 1.27.0, the gateway for any HTTP resource in 1.30.0, and backend OAuth identity plus per-tool blocking in 1.31.0. At a high level, the big features we're working on next are:

• Keycloak RFC 8693 token exchange for OBO (1.32.0): standards-based on-behalf-of exchange for Keycloak deployments, which today cannot use the OBO egress path or backend discovery because Keycloak binds the token audience with a server-side mapper rather than a request scope.
• Client ID Metadata Documents for coding assistants: the registry publishes its own CIMD as of 1.31.0, currently shipping disabled. Next is the identity-provider side, so an assistant connects with the least friction across providers without a pre-registered client ID.
• Registry Copilot: an embedded chat and agent-builder experience for discovering assets and composing agents from inside the registry. Tracked as #744; not yet scheduled to a release.

Have a feature request? Please open a GitHub issue, we build in the open.

Documentation

Full documentation is on the documentation site, and every guide also lives in the docs/ folder. Stuck or have a question? Start with the FAQ / Troubleshooting guide: it covers the most common setup, auth, deployment, and registration issues.

High-traffic pages by audience:

Get started

• Quick Start · Installation Guide · Configuration Reference · FAQ / Troubleshooting

Platform & security

• Authentication Guide · Access Control & Scopes · Gateway Proxy Guide · AWS ECS Deployment · Amazon EKS (Helm) · Observability · Federation · Forward-Proxy Egress

Architecture & development

• Architecture Diagrams · API Reference · AI Coding Assistant Integration · MCP Registry CLI

Design decisions

• Architecture Decision Records (ADRs) · ADR 0001: No server-side DCR

Telemetry

The registry collects anonymous, non-sensitive usage telemetry (version, OS, cloud provider, aggregate asset counts) to understand adoption. It is opt-out and on by default; no PII, credentials, endpoints, or model names are ever sent. Disable everything with MCP_TELEMETRY_DISABLED=1. Full schema and privacy guarantees: Telemetry Documentation.

Community

• GitHub Discussions, feature requests and general discussion
• GitHub Issues, bug reports and feature requests
• Roadmap (GitHub Milestones), upcoming releases and their issues
• Contributing Guide · Code of Conduct · Security Policy

Star History

View the full interactive star-growth chart at star-history.com.

License

Licensed under the Apache-2.0 License. See LICENSE for details.