# agentic-community/mcp-gateway-registry architecture

> Architecture diagram of the GitHub repository agentic-community/mcp-gateway-registry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agentic-community/mcp-gateway-registry
- Repository: https://github.com/agentic-community/mcp-gateway-registry

## Overview

The repository is the MCP Gateway & Registry: a governed control plane for registering and discovering MCP servers, agents, skills, and other assets, paired with an authenticated gateway data plane. The principal workflow is users or agents connecting through the gateway, which delegates authentication and routes to registered backends; registry APIs manage assets and access policy. The README also documents natural-language discovery, audit, per-user OAuth egress, and A2A discovery. Source excerpts are partial, so unsampled subsystem links are included only where the README documents them.

Main entry points: [`registry/core/nginx_service.py`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/core/nginx_service.py) (nginx gateway), [`registry/main.py`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/main.py) (Registry API), [`registry/api/server_routes.py`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/api/server_routes.py) (Asset routes), [`auth_server/server.py`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/auth_server/server.py) (Auth server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway data plane"]
  node_gateway["nginx gateway<br/>[nginx_service.py]"]
  node_egress_oauth["Egress OAuth<br/>[oauth_engine.py]"]
  node_url_guard["SSRF protection<br/>[url_guard.py]"]
end

subgraph group_registry["Registry control plane"]
  node_registry_api["Registry API<br/>[main.py]"]
  node_asset_routes["Asset routes<br/>[server_routes.py]"]
  node_asset_services["Asset services<br/>[server_service.py]"]
  node_repositories["Repository factory<br/>[factory.py]"]
  node_documentdb[("DocumentDB search")]
  node_semantic_search["Semantic discovery"]
  node_embeddings_admin["Embedding administration"]
  node_web_ui["Registry UI<br/>[App.tsx]"]
end

subgraph group_identity["Identity and audit"]
  node_auth["Auth server<br/>[server.py]"]
  node_access["Access control<br/>[dependencies.py]"]
  node_auth_flows["OAuth login<br/>[routes.py]"]
  node_audit["Audit logging<br/>[service.py]"]
end

subgraph group_federation["Discovery and federation"]
  node_federation["Federation ingestion"]
  node_a2a_assistant["Travel assistant<br/>[server.py]"]
end

node_users(("Human users"))
node_agents(("AI agents"))
node_backends["MCP and agent backends"]
node_identity_provider["Identity provider"]

node_users -->|"connects through"| node_gateway
node_agents -->|"connect through"| node_gateway
node_gateway -->|"validates via"| node_auth
node_gateway -->|"routes to"| node_registry_api
node_gateway -->|"routes to"| node_backends
node_auth -->|"validates against"| node_identity_provider
node_registry_api -->|"registers routes"| node_asset_routes
node_asset_routes -->|"calls"| node_asset_services
node_asset_services -->|"gets repository"| node_repositories
node_repositories -->|"creates search store"| node_documentdb
node_asset_routes -->|"checks access"| node_access
node_auth_flows -->|"redirects login"| node_auth
node_gateway -->|"supports user OAuth"| node_egress_oauth
node_registry_api -->|"records calls"| node_audit
node_users -->|"discovers assets"| node_semantic_search
node_embeddings_admin -->|"manages embeddings"| node_documentdb
node_federation -->|"indexes ingested assets"| node_documentdb
node_agents -.->|"uses A2A discovery"| node_a2a_assistant
node_users -.->|"manages assets"| node_web_ui
node_egress_oauth -->|"validates URLs"| node_url_guard

click node_gateway "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/core/nginx_service.py"
click node_auth "https://github.com/agentic-community/mcp-gateway-registry/blob/main/auth_server/server.py"
click node_registry_api "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/main.py"
click node_asset_routes "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/api/server_routes.py"
click node_asset_services "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/server_service.py"
click node_repositories "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/repositories/factory.py"
click node_documentdb "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/repositories/documentdb/search_repository.py"
click node_access "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/auth/dependencies.py"
click node_auth_flows "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/auth/routes.py"
click node_audit "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/audit/service.py"
click node_egress_oauth "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/egress_auth/oauth_engine.py"
click node_semantic_search "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/semantic_search_service.py"
click node_embeddings_admin "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/api/embeddings_admin_routes.py"
click node_url_guard "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/utils/url_guard.py"
click node_federation "https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/ard_ingestion_service.py"
click node_a2a_assistant "https://github.com/agentic-community/mcp-gateway-registry/blob/main/agents/a2a/src/travel-assistant-agent/server.py"
click node_web_ui "https://github.com/agentic-community/mcp-gateway-registry/blob/main/frontend/src/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_egress_oauth,node_url_guard,node_users toneBlue
class node_registry_api,node_asset_routes,node_asset_services,node_repositories,node_documentdb,node_semantic_search,node_embeddings_admin,node_web_ui toneAmber
class node_auth,node_access,node_auth_flows,node_audit toneMint
class node_federation,node_a2a_assistant toneRose
class node_agents,node_backends,node_identity_provider toneIndigo
```

## Components

### Gateway data plane

- [nginx gateway](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/core/nginx_service.py): `registry/core/nginx_service.py`
- [Egress OAuth](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/egress_auth/oauth_engine.py): `registry/egress_auth/oauth_engine.py`
- [SSRF protection](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/utils/url_guard.py): `registry/utils/url_guard.py`

### Registry control plane

- [Registry API](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/main.py): `registry/main.py`
- [Asset routes](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/api/server_routes.py): `registry/api/server_routes.py`
- [Asset services](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/server_service.py): `registry/services/server_service.py`
- [Repository factory](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/repositories/factory.py): `registry/repositories/factory.py`
- [DocumentDB search](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/repositories/documentdb/search_repository.py): `registry/repositories/documentdb/search_repository.py`
- [Semantic discovery](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/semantic_search_service.py): `registry/services/semantic_search_service.py`
- [Embedding administration](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/api/embeddings_admin_routes.py): `registry/api/embeddings_admin_routes.py`
- [Registry UI](https://github.com/agentic-community/mcp-gateway-registry/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Identity and audit

- [Auth server](https://github.com/agentic-community/mcp-gateway-registry/blob/main/auth_server/server.py): `auth_server/server.py`
- [Access control](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/auth/dependencies.py): `registry/auth/dependencies.py`
- [OAuth login](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/auth/routes.py): `registry/auth/routes.py`
- [Audit logging](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/audit/service.py): `registry/audit/service.py`

### Discovery and federation

- [Federation ingestion](https://github.com/agentic-community/mcp-gateway-registry/blob/main/registry/services/ard_ingestion_service.py): `registry/services/ard_ingestion_service.py`
- [Travel assistant](https://github.com/agentic-community/mcp-gateway-registry/blob/main/agents/a2a/src/travel-assistant-agent/server.py): `agents/a2a/src/travel-assistant-agent/server.py`

### Other components

- **Human users**
- **AI agents**
- **MCP and agent backends**
- **Identity provider**

## Connections

- Human users → nginx gateway: connects through (evidence: `README.md`)
- AI agents → nginx gateway: connect through (evidence: `README.md`)
- nginx gateway → Auth server: validates via (evidence: `README.md`)
- nginx gateway → Registry API: routes to (evidence: `README.md`)
- nginx gateway → MCP and agent backends: routes to (evidence: `README.md`)
- Auth server → Identity provider: validates against (evidence: `README.md`)
- Registry API → Asset routes: registers routes (evidence: `registry/main.py`)
- Asset routes → Asset services: calls (evidence: `registry/api/server_routes.py`)
- Asset services → Repository factory: gets repository (evidence: `registry/services/server_service.py`)
- Repository factory → DocumentDB search: creates search store (evidence: `registry/repositories/factory.py`)
- Asset routes → Access control: checks access (evidence: `registry/api/server_routes.py`)
- OAuth login → Auth server: redirects login (evidence: `registry/auth/routes.py`)
- nginx gateway → Egress OAuth: supports user OAuth (evidence: `README.md`)
- Registry API → Audit logging: records calls (evidence: `README.md`)
- Human users → Semantic discovery: discovers assets (evidence: `README.md`)
- Embedding administration → DocumentDB search: manages embeddings (evidence: `registry/api/embeddings_admin_routes.py`)
- Federation ingestion → DocumentDB search: indexes ingested assets (evidence: `registry/services/ard_ingestion_service.py`)
- AI agents → Travel assistant: uses A2A discovery (evidence: `README.md`)
- Human users → Registry UI: manages assets (evidence: `README.md`)
- Egress OAuth → SSRF protection: validates URLs (evidence: `registry/egress_auth/oauth_engine.py`)
