Skip to content

Commit 25c3185

Browse files
aarora79aarora79
committed
Enhance docs/auth.md with updated architecture and explanations
- Update architecture diagram to show separate components (Nginx, Auth Server, Registry) - Add Client Layer showing User, CLI Auth Tool, and AI Agent interactions - Show clear separation between infrastructure components - Add detailed component explanations for entry-level developers - Include references to docs/cognito.md for detailed setup instructions - Improve accessibility with component descriptions and cross-references - Addresses issue #15
1 parent 395167e commit 25c3185

File tree

1 file changed

+84
-36
lines changed

1 file changed

+84
-36
lines changed

‎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)