authmcp-gateway 1.0.20

Universal Authentication Gateway for MCP (Model Context Protocol) Servers

AuthMCP Gateway

Secure authentication proxy for Model Context Protocol (MCP) servers

AuthMCP Gateway provides centralized authentication, authorization, and monitoring for MCP servers. It acts as a secure proxy between clients and your MCP backends, adding JWT-based authentication, rate limiting, real-time monitoring, and comprehensive security logging.

📋 Table of Contents

• ✨ Features
• 📚 Documentation
• 📸 Screenshots
• 🚀 Quick Start
• ⚙️ Configuration
• 💡 Usage
• 🏗️ Architecture
• 🔌 API Endpoints
• 🔐 Security
• 🛠️ Development
• 📊 Monitoring
• 🔧 Troubleshooting

---

✨ Features

🔐 Authentication & Authorization

• OAuth 2.0 + JWT - Industry-standard authentication flow
• User Management - Multi-user support with role-based access
• Backend Token Management - Secure storage and auto-refresh of MCP server credentials
• Rate Limiting - Per-user request throttling with configurable limits

📊 Real-Time Monitoring

• Live MCP Activity Monitor - Real-time request feed with auto-refresh
• Performance Metrics - Response times, success rates, requests/minute
• Security Event Logging - Unauthorized access attempts, rate limiting, suspicious activity
• Health Checking - Automatic health checks for all connected MCP servers

🎛️ Admin Dashboard

• User Management - Create, edit, and manage users
• MCP Server Configuration - Add and configure backend MCP servers
• Token Management - Monitor token health and manual refresh
• Security Events - View and filter security events
• API Testing - Built-in MCP testing interface

🛡️ Security

• JWT token-based authentication with refresh tokens
• Secure credential storage with encrypted database support
• CORS protection and request validation
• Security event logging and monitoring
• File-based logging - JSON logs for auth & MCP requests with rotation; security events remain in SQLite for audit/queries
• Built-in security testing guide

📚 Documentation

📚 Complete Documentation - Full documentation index

Quick Links:

• Deployment Guide - Production setup with HTTPS, Docker, cloud platforms
• Logging Architecture - File-based logging, log formats, analysis
• API Reference - REST API documentation with examples
• Security Testing - Security verification and testing
• Publishing Guide - Publishing to PyPI

📸 Screenshots

🖥️ Dashboard - Real-time Overview

Live statistics, server health monitoring, top tools usage, and recent activity feed

🔧 MCP Servers - Connection Management

Manage backend MCP server connections with status monitoring and health checks

📊 MCP Activity Monitor - Real-time Request Tracking

Monitor live MCP requests with detailed metrics, top tools ranking, and request feed

🛡️ Security Events - Threat Detection

Track security events, rate limiting, suspicious payloads, and unauthorized access attempts

🔒 MCP Security Audit - Vulnerability Scanner

Test any MCP server for security vulnerabilities with comprehensive automated checks

---

🚀 Quick Start

Option 1: PyPI Package (Recommended)

1. Install:

pip install authmcp-gateway

2. First Run:

authmcp-gateway start
# ✓ Auto-creates .env with JWT_SECRET_KEY
# ✓ Auto-creates data/ directory
# ✓ Initializes database

3. Access Setup Wizard: Open http://localhost:8000/ in your browser to create admin user.

4. Optional - Customize Configuration:

# Edit auto-generated .env or download full example
curl -o .env https://raw.githubusercontent.com/loglux/authmcp-gateway/main/.env.example.pypi

# Common settings to customize in .env:
# PORT=9000                          # Change server port
# PASSWORD_REQUIRE_SPECIAL=false     # Relax password requirements
# LOG_LEVEL=DEBUG                    # More detailed logs

# Restart to apply changes
authmcp-gateway start

Available Commands:

authmcp-gateway start                    # Start server (default: 0.0.0.0:8000)
authmcp-gateway start --port 9000        # Start on custom port
authmcp-gateway start --host 127.0.0.1   # Bind to localhost only
authmcp-gateway start --env-file custom.env  # Use custom config file

authmcp-gateway init-db                  # Initialize database
authmcp-gateway create-admin             # Create admin user via CLI
authmcp-gateway version                  # Show version
authmcp-gateway --help                   # Show all options

Option 2: Docker Compose

1. Clone and configure:

   git clone https://github.com/loglux/authmcp-gateway.git
   cd authmcp-gateway
   cp .env.example .env
   # Edit .env with your settings
   

2. Start the gateway:

   docker-compose up -d
   

3. Access admin panel:

   • Open http://localhost:9105/
   • Complete setup wizard to create admin user
   • Add your MCP servers

⚙️ Configuration

Environment Variables

# Gateway Settings
GATEWAY_PORT=9105              # Host port mapping for Docker (container listens on 8000)
JWT_SECRET_KEY=your-secret-key # JWT signing key (auto-generated if not set)
AUTH_REQUIRED=true             # Enable authentication (default: true)

# Admin Settings
ADMIN_USERNAME=admin           # Initial admin username
ADMIN_PASSWORD=secure-password # Initial admin password

Adding MCP Servers

Via Admin Panel:

1. Navigate to MCP Servers → Add Server
2. Enter server details:
   • Name (e.g., "GitHub MCP")
   • URL (e.g., "http://github-mcp:8000/mcp")
   • Backend token (if required)

Via API:

curl -X POST http://localhost:9105/admin/api/mcp-servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub MCP",
    "url": "http://github-mcp:8000/mcp",
    "backend_token": "optional-token"
  }'

💡 Usage

For End Users

1. Login to get access token:

   curl -X POST http://localhost:9105/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"your-username","password":"your-password"}'
   

2. Use token to access MCP endpoints:

   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"}'
   

For Administrators

Admin Panel Features:

• Dashboard - Overview of users, servers, and activity
• MCP Activity - Real-time monitoring of all MCP requests
• Security Events - View unauthorized access attempts and suspicious activity
• User Management - Create and manage user accounts
• Token Management - Monitor and refresh backend tokens

🏗️ Architecture

┌─────────────┐
│   Client    │
│  (Claude,   │
│   etc.)     │
└──────┬──────┘
       │ JWT Auth
       ▼
┌─────────────────────────────┐
│   AuthMCP Gateway           │
│                             │
│  • Authentication           │
│  • Rate Limiting            │
│  • Security Logging         │
│  • Request Routing          │
│  • Health Monitoring        │
└──────┬──────────────────────┘
       │
       ├──────────┬──────────┬──────────┐
       ▼          ▼          ▼          ▼
  ┌─────────┐ ┌────────┐ ┌────────┐ ┌────────┐
  │GitHub   │ │  RAG   │ │ Home   │ │Custom  │
  │MCP      │ │  MCP   │ │Assistant│ │ MCP    │
  └─────────┘ └────────┘ └────────┘ └────────┘

🔌 API Endpoints

Public Endpoints

• POST /auth/login - User login
• POST /auth/register - User registration (if enabled)
• POST /auth/refresh - Refresh access token
• POST /oauth/register - OAuth dynamic client registration (if enabled)
• GET /.well-known/oauth-authorization-server - OAuth discovery

Protected Endpoints

• POST /mcp - Aggregated MCP endpoint (all servers)
• POST /mcp/{server_name} - Specific MCP server endpoint
• GET /mcp - Streamable MCP endpoint (SSE/stream clients)
• GET /auth/me - Current user info
• POST /auth/logout - Logout

Admin Endpoints

• GET /admin - Admin dashboard
• GET /admin/mcp-activity - Real-time MCP monitoring
• GET /admin/security-logs - Security events
• GET /admin/users - User management
• GET /admin/mcp-servers - MCP server configuration
• Plus full REST API for management

🤖 Codex OAuth (DCR) Login (Manual Callback)

Codex uses OAuth Authorization Code + PKCE and Dynamic Client Registration (DCR). When running in a terminal without an auto-launching browser, you must manually open the authorization URL and then call the localhost callback URL yourself to finish the login.

See the wiki page: Codex-Registration for a full CLI transcript.

Steps:

1. Add the MCP server in Codex:

codex mcp add rag --url https://your-domain.com/mcp/your-backend

2. Codex prints an Authorize URL. Open it in your browser.
3. Complete the login (admin/user credentials).
4. After successful login you will be redirected to a http://127.0.0.1:<port>/callback?... URL. Copy that full URL and call it from another terminal:

curl "http://127.0.0.1:<port>/callback?code=...&state=..."

You should see: Authentication complete. You may close this window.

Once completed, Codex shows the MCP server as logged in.

Calling RAG Tools From Codex (Example)

In Codex chat, you can invoke tools directly, for example:

• mcp__rag__list_knowledge_bases
• mcp__rag__rag_query

Or ask Codex to list tools: show rag tools.

🔐 Security

Testing Security

See docs/SECURITY_TESTING.md for:

• Manual security tests
• Automated testing script
• Production deployment checklist
• Security best practices

Security Features

• ✅ JWT-based authentication with refresh tokens
• ✅ Rate limiting per user
• ✅ Security event logging
• ✅ MCP request tracking with suspicious activity detection
• ✅ Health monitoring for backend servers
• ✅ CORS protection
• ✅ Secure credential storage

🛠️ Development

Local Development

# Clone repository
git clone https://github.com/loglux/authmcp-gateway.git
cd authmcp-gateway

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -e .

# Run gateway
authmcp-gateway

Running Tests

pytest tests/

Project Structure

authmcp-gateway/
├── src/authmcp_gateway/
│   ├── admin/           # Admin panel routes and logic
│   ├── auth/            # Authentication & authorization
│   ├── mcp/             # MCP proxy and handlers
│   ├── security/        # Security logging and monitoring
│   ├── middleware.py    # Request middleware
│   └── app.py           # Main application
├── templates/           # Jinja2 templates (admin UI)
├── docs/                # Documentation
├── tests/               # Test suite
└── docker-compose.yml   # Docker deployment

📊 Monitoring

Real-Time Dashboard

Access /admin/mcp-activity for:

• Live request feed (updates every 3 seconds)
• Requests per minute
• Average response times
• Success rates
• Top tools usage
• Per-server statistics

Logs

View logs in real-time:

docker logs -f authmcp-gateway

🔧 Troubleshooting

Cannot access admin panel:

• Ensure you've completed the setup wizard at /setup
• Check that cookies are enabled
• Verify JWT_SECRET_KEY is set correctly

MCP server shows as offline:

• Check server URL is correct and reachable
• Verify backend token if required
• View error details in MCP Servers page

401 Unauthorized errors:

• Token may have expired - use refresh token
• Verify Authorization header format: Bearer YOUR_TOKEN
• Check user has permission for the MCP server

For more help, see docs/SECURITY_TESTING.md.

License

MIT License - see LICENSE file for details.