AuthMCP Gateway is a security authentication proxy for MCP (Model Context Protocol) servers, providing centralized authentication, authorization, and monitoring capabilities. It can transparently proxy all MCP capabilities of multiple backend MCP servers—tools, resources, prompts, and completions—and provides services externally through a single authentication endpoint.
Main capabilities
- Full MCP protocol proxy (v1.2.0): supports tools/list, tools/call (intelligent routing: prefix, mapping, auto-discovery), resources/list, resources/read, resources/templates/list, prompts/list, prompts/get, completion/complete (ref-based routing). Dynamically queries backend capabilities during initialization and only advertises the capabilities it supports. Multi-server aggregation: list methods merge results from all backends, and read/get/call are routed to the correct backend. The protocol version is MCP 2025-03-26.
- Authentication and authorization: OAuth 2.0 + JWT, supports the OAuth 2.0 authorization code flow and Dynamic Client Registration (DCR), enabling MCP clients such as Codex to register and authenticate on their own; multi-user and role-based access; secure storage and automatic refresh of backend tokens; per-user rate limiting; CORS protection and request validation; security event logging.
- Real-time monitoring: real-time MCP activity monitoring with automatic refresh; performance metrics (response time, success rate, requests per minute); security event logs (unauthorized access, rate limiting, suspicious activity); automatic health checks for backend servers; file-based JSON logs (authentication and MCP requests, with rotation), with security events stored in SQLite for auditing and querying.
- Admin backend: user management (create, edit), MCP server configuration, token management and manual refresh, security event viewing and filtering, MCP vulnerability scanning. The dashboard provides real-time statistics, server health monitoring, popular tool usage, and recent activity.
Usage Installation and deployment: Option 1: PyPI package (recommended). After installation, open http://localhost:8000/ to enter the setup wizard and create an administrator user; the configuration can be customized via commands. Option 2: Docker Compose. Clone the repository and configure: git clone https://github.com/loglux/authmcp-gateway.git && cd authmcp-gateway && cp .env.example .env, edit .env, then start with docker-compose up -d. Access the admin panel:http://localhost:9105/，完成设置向导创建管理员用户，添加 MCP server.
Add an MCP server: in the admin panel, navigate to MCP Servers → Add Server, enter the name (e.g. "GitHub MCP"), URL (e.g. http://github-mcp:8000/mcp）及后端令牌（如需要）。
Invocation example: Log in to obtain an access token: curl -X POST http://localhost:9105/auth/login -H "Content-Type: application/json" -d '{"username":"your-username","password":"your-password"}'
Use the token to access the MCP endpoint: curl -X POST http://localhost:9105/mcp -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
API Endpoints Public endpoints: POST /auth/login, POST /auth/register (if enabled), POST /auth/refresh, POST /oauth/register (if enabled), GET /.well-known/oauth-authorization-server. Protected endpoints: POST /mcp (aggregates all servers), POST /mcp/{server_name} (specified server), GET /mcp (streaming SSE/stream client), GET /auth/me, POST /auth/logout.
Tool Annotations and Safe Retries For tools/call, the gateway prioritizes standard MCP tool annotations to determine whether a tool is read-only or safe to retry: annotations.readOnlyHint, annotations.idempotentHint, annotations.destructiveHint. Read-only tools can use safe automatic retries; mutating tools are not blindly retried; if a mutating tool is marked idempotent, the gateway preserves or generates arguments.idempotency_key and reuses it on retry; if metadata is missing or ambiguous, it falls back to conservative behavior, disabling automatic retries for tools/call.
Codex OAuth (DCR) login (manual callback) Codex uses OAuth authorization code + PKCE and DCR. When running in a terminal that does not automatically launch a browser, you need to manually open the authorization URL and then call the localhost callback URL yourself to complete login. After adding the MCP server in Codex, Codex prints the Authorize URL; open it in a browser and complete login. After success, it redirects to http://127.0.0.1:<port>/callback?... URL; copy the full URL and call it in another terminal. After seeing "Authentication complete", Codex will show that the MCP server is logged in.
Headless server token storage: On a server without a desktop environment, Codex cannot access the OS keyring to store OAuth tokens, causing an "Auth required" error even after successful login. You need to switch to file-based token storage (refer to the Codex configuration reference); otherwise Codex cannot refresh tokens and requires repeated manual logins. Restart Codex after updating the configuration.
Discovery compatibility: Some MCP clients probe OpenID discovery using non-standard paths after a successful token exchange. In addition to the standard /.well-known/openid-configuration, the gateway also provides the same discovery document at /oauth/token/.well-known/openid-configuration as a compatibility alias.
Codex multi-machine note: If Codex runs on multiple machines, each machine stores local tokens. When Enforce Single Session (one active token per user) is enabled, logging in on one machine may invalidate the token on another machine. In multi-machine scenarios, it is recommended to disable Enforce Single Session in the admin settings.
Security Features JWT authentication and refresh tokens, per-user rate limiting, security event logging, MCP request tracing and suspicious activity detection, backend server health monitoring, CORS protection, secure credential storage (supports encrypted database).
Use Cases Organizations or developers that need unified authentication, authorization, and monitoring for multiple MCP servers; scenarios where MCP clients self-register via OAuth/DCR; environments that need real-time monitoring of MCP activity and security auditing.
Limitations The material does not provide information about charges, pricing, specific platform support, or performance guarantees. Deployment requires Docker or a Python environment, and some features (such as OAuth/DCR and user registration) must be enabled in the configuration. Headless servers require additional token storage configuration.
License: MIT, see the LICENSE file for details.
