Skip to content

Commit 1af2579

Browse files
aarora79aarora79
authored
Merge pull request #22 from agentic-community/enhance-auth-docs
Enhance docs/auth.md with Updated Architecture and Explanations
2 parents 395167e + 2f05400 commit 1af2579

File tree

2 files changed

+105
-45
lines changed

2 files changed

+105
-45
lines changed

‎README.md

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
<img src="registry/static/mcp_gateway_horizontal_white_logo.png" alt="MCP Gateway Logo" width="100%">
22

3-
# ⚠️ ACTIVE DEVELOPMENT - WORK IN PROGRESS ⚠️
43

5-
> **WARNING**: This repository is under active development. Expect frequent updates and breaking changes as we improve functionality and refine APIs. We recommend pinning to specific versions for production use. Star the repository to track our progress!
6-
7-
![Under Construction](https://img.shields.io/badge/Status-Under%20Construction-yellow)
8-
![Stability](https://img.shields.io/badge/API%20Stability-Experimental-orange)
94
![GitHub stars](https://img.shields.io/github/stars/agentic-community/mcp-gateway-registry?style=flat&logo=github)
105
![GitHub forks](https://img.shields.io/github/forks/agentic-community/mcp-gateway-registry?style=flat&logo=github)
116
![GitHub issues](https://img.shields.io/github/issues/agentic-community/mcp-gateway-registry?style=flat&logo=github)
@@ -61,12 +56,21 @@ flowchart TB
6156
RP["Reverse Proxy Router"]
6257
end
6358
59+
subgraph AuthRegistry["Authentication & Registry Services"]
60+
AuthServer["Auth Server<br/>(Dual Auth)"]
61+
Registry["Registry<br/>Web UI"]
62+
RegistryMCP["Registry<br/>MCP Server"]
63+
end
64+
6465
subgraph LocalMCPServers["Local MCP Servers"]
6566
MCP_Local1["MCP Server 1"]
6667
MCP_Local2["MCP Server 2"]
6768
end
6869
end
6970
71+
%% Identity Provider
72+
IdP[Identity Provider<br/>Amazon Cognito]
73+
7074
subgraph EKS_Cluster["Amazon EKS/EC2 Cluster"]
7175
MCP_EKS1["MCP Server 3"]
7276
MCP_EKS2["MCP Server 4"]
@@ -87,10 +91,16 @@ flowchart TB
8791
end
8892
8993
%% Connections from Agents to Gateway
90-
Agent1 -->|MCP Protocol<br>SSE| RP
91-
Agent2 -->|MCP Protocol<br>SSE| RP
92-
Agent3 -->|MCP Protocol<br>Streamable HTTP| RP
93-
AgentN -->|MCP Protocol<br>Streamable HTTP| RP
94+
Agent1 -->|MCP Protocol<br>SSE with Auth| RP
95+
Agent2 -->|MCP Protocol<br>SSE with Auth| RP
96+
Agent3 -->|MCP Protocol<br>Streamable HTTP with Auth| RP
97+
AgentN -->|MCP Protocol<br>Streamable HTTP with Auth| RP
98+
99+
%% Auth flow connections
100+
RP -->|Auth validation| AuthServer
101+
AuthServer -.->|Validate credentials| IdP
102+
RP -->|Tool discovery| RegistryMCP
103+
RP -->|Web UI access| Registry
94104
95105
%% Connections from Gateway to MCP Servers
96106
RP -->|SSE| MCP_Local1
@@ -124,6 +134,8 @@ flowchart TB
124134
class Agent1,Agent2,Agent3,AgentN agent
125135
class EC2_Gateway,NGINX gateway
126136
class RP nginx
137+
class AuthServer,Registry,RegistryMCP gateway
138+
class IdP apiGw
127139
class MCP_Local1,MCP_Local2 mcpServer
128140
class EKS_Cluster,MCP_EKS1,MCP_EKS2 eks
129141
class API_GW apiGw

‎docs/auth.md

Lines changed: 84 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -19,59 +19,107 @@ The MCP gateway and Registry provides an enterprise ready solution that integrat
1919
Here is an architecture diagram of the system.
2020

2121
```mermaid
22-
graph LR
23-
%% AI Agent
24-
Agent[AI Agent]
25-
26-
%% CLI Auth Tool
27-
CLIAuth[CLI Auth Tool]
28-
29-
%% Identity Provider
30-
IdP[Identity Provider]
22+
graph TB
23+
%% Users and Agents at same level - stacked on top
24+
subgraph Clients["Client Layer"]
25+
direction TB
26+
User[User<br/>Human Administrator]
27+
CLIAuth[CLI Auth Tool]
28+
Agent[AI Agent]
29+
User --- CLIAuth
30+
end
3131
32-
%% Gateway and Registry Block
33-
subgraph GwReg["Gateway & Registry"]
34-
Gateway["Gateway<br/>(Reverse Proxy)"]
35-
Registry[Registry]
32+
%% MCP Gateway & Registry Components (Separate)
33+
subgraph Infrastructure["MCP Gateway & Registry Infrastructure"]
34+
direction TB
35+
Nginx["Nginx<br/>Reverse Proxy"]
3636
AuthServer["Auth Server<br/>(Dual Auth)"]
37+
Registry["Registry<br/>Web UI"]
38+
RegistryMCP["Registry<br/>MCP Server"]
3739
end
3840
41+
%% Identity Provider
42+
IdP[Identity Provider<br/>Amazon Cognito]
43+
3944
%% MCP Server Farm
4045
subgraph MCPFarm["MCP Server Farm"]
41-
MCP1[MCP Server 1]
42-
MCP2[MCP Server 2]
43-
MCP3[MCP Server 3]
44-
MCPn[MCP Server n]
46+
direction TB
47+
MCP1[MCP Server 1<br/>CurrentTime]
48+
MCP2[MCP Server 2<br/>FinInfo]
49+
MCP3[MCP Server 3<br/>Custom]
50+
MCPn[MCP Server n<br/>...]
4551
end
4652
47-
%% Connections
48-
Agent -->|Discover servers/tools| Registry
49-
Agent -->|Data plane requests| Gateway
50-
Gateway -->|Auth verification| AuthServer
51-
Gateway -->|Proxy requests| MCP1
52-
Gateway -->|Proxy requests| MCP2
53-
Gateway -->|Proxy requests| MCP3
54-
Gateway -->|Proxy requests| MCPn
53+
%% All connections go through gateway/registry only
54+
User -->|1. Web UI access<br/>Server management| Nginx
55+
User -->|2. Registry access<br/>Tool discovery| Registry
56+
57+
Agent -->|1. Discover tools<br/>with auth headers| Nginx
58+
Agent -->|2. MCP requests<br/>with auth headers| Nginx
5559
56-
%% Auth flow
57-
IdP -.->|M2M: JWT tokens| Agent
58-
IdP -.->|User: OAuth flow| CLIAuth
59-
CLIAuth -.->|Session cookie| Agent
60-
AuthServer -.->|Validate tokens/cookies| IdP
60+
%% Internal routing
61+
Nginx -->|Route /mcpgw/*<br/>Auth validation| AuthServer
62+
Nginx -->|Route /mcpgw/*<br/>Tool discovery| RegistryMCP
63+
Nginx -->|Route /registry/*<br/>Web UI| Registry
64+
Nginx -->|Route /server1/*<br/>Proxy to MCP servers| MCP1
65+
Nginx -->|Route /server2/*<br/>Proxy to MCP servers| MCP2
66+
Nginx -->|Route /serverN/*<br/>Proxy to MCP servers| MCP3
67+
Nginx -->|Route /serverN/*<br/>Proxy to MCP servers| MCPn
68+
69+
%% Auth flows
70+
IdP -.->|M2M: JWT tokens<br/>Client Credentials| Agent
71+
IdP -.->|User: OAuth PKCE flow<br/>Authorization Code| CLIAuth
72+
CLIAuth -.->|Session cookie<br/>Signed with SECRET_KEY| User
73+
AuthServer -.->|Validate JWT/cookies<br/>Get user groups/scopes| IdP
74+
75+
%% Registry management (User-driven)
76+
Registry -->|Server registration<br/>Health monitoring| RegistryMCP
77+
RegistryMCP -->|Tool metadata<br/>Health checks| MCP1
78+
RegistryMCP -->|Tool metadata<br/>Health checks| MCP2
79+
RegistryMCP -->|Tool metadata<br/>Health checks| MCP3
80+
RegistryMCP -->|Tool metadata<br/>Health checks| MCPn
6181
6282
%% Styling
83+
classDef userStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
6384
classDef agentStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
85+
classDef clientStyle fill:#f5f5f5,stroke:#424242,stroke-width:2px
6486
classDef idpStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
65-
classDef gwregStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
66-
classDef mcpStyle fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
87+
classDef nginxStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
88+
classDef authStyle fill:#ffebee,stroke:#c62828,stroke-width:2px
89+
classDef registryStyle fill:#fff8e1,stroke:#f57f17,stroke-width:2px
90+
classDef mcpStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
6791
classDef cliStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px
6892
93+
class Clients clientStyle
94+
class User userStyle
6995
class Agent agentStyle
7096
class IdP idpStyle
71-
class Gateway,Registry,AuthServer gwregStyle
97+
class Nginx nginxStyle
98+
class AuthServer authStyle
99+
class Registry,RegistryMCP registryStyle
72100
class MCP1,MCP2,MCP3,MCPn mcpStyle
73101
class CLIAuth cliStyle
74102
```
103+
### Architecture Components Explained
104+
105+
The updated architecture diagram above shows the clear separation of components that work together to provide secure, enterprise-ready MCP access:
106+
107+
#### Client Layer
108+
- **User (Human Administrator)**: Manages the registry through the web UI, registers new MCP servers, and monitors system health
109+
- **CLI Auth Tool**: Handles OAuth authentication flows for users, creating session cookies for web UI access
110+
- **AI Agent**: Programmatic clients that discover and invoke MCP tools with proper authentication
111+
112+
#### MCP Gateway & Registry Infrastructure
113+
- **Nginx Reverse Proxy**: Single entry point that routes all requests and handles SSL termination
114+
- **Auth Server**: Validates JWT tokens and session cookies against Amazon Cognito, enforces fine-grained access control
115+
- **Registry Web UI**: Administrative interface for managing MCP servers and viewing system status
116+
- **Registry MCP Server**: Provides tool discovery capabilities to agents, returns filtered results based on permissions
117+
118+
#### External Components
119+
- **Amazon Cognito**: Identity Provider (IdP) that handles user authentication and group management
120+
- **MCP Server Farm**: Collection of individual MCP servers providing various tools and capabilities
121+
122+
> **For detailed setup instructions**, see the comprehensive guide in [`docs/cognito.md`](cognito.md) which covers both user identity and agent identity authentication modes.
75123
76124
At a high-level the flow works as follows:
77125

@@ -168,7 +216,7 @@ The above implementation provides an OAuth compliant way to MCP security without
168216

169217
This section discusses the reference implementation using Amazon Cognito as the IdP, supporting both Machine-to-Machine (M2M) and Session Cookie authentication methods.
170218

171-
>This section will soon be updated with detailed steps for Cognito configuration.
219+
>For comprehensive Cognito setup instructions, see [`docs/cognito.md`](cognito.md) which covers both user identity and agent identity authentication modes with step-by-step configuration guides.
172220
173221
### Key Components
174222

@@ -208,7 +256,7 @@ Run the Agent with the following command:
208256
```{.bash}
209257
python agents/agent_w_auth.py
210258
```
211-
1. Copy `agents/.env.template` to `agents/.env.agent` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`) as appropriate for your setup.
259+
1. Copy `agents/.env.template` to `agents/.env.agent` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`) as appropriate for your setup. For detailed Cognito configuration steps, see [`docs/cognito.md`](cognito.md).
212260
1. Agent startup:
213261
- Configured with client ID, client secret, and a set of scopes. _Each agent is an App Client in a Cognito user pool_.
214262
- Requests scopes (e.g., MCP Registry with tool finder and basic MCP servers)
@@ -257,7 +305,7 @@ Required environment variables:
257305

258306
##### b. Agent with Session Cookie Support
259307

260-
Copy `agents/.env.template` to `agents/.env.user` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`, `SECRET_KEY`) as appropriate for your setup.
308+
Copy `agents/.env.template` to `agents/.env.user` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`, `SECRET_KEY`) as appropriate for your setup. For detailed Cognito configuration steps, see [`docs/cognito.md`](cognito.md).
261309

262310
The agent (`agents/agent_w_auth.py`) supports session cookie authentication:
263311

0 commit comments

Comments
 (0)