Skip to main content

Authentication

MCP Gatekeeper uses token-based authentication to secure API endpoints.

Overview​

Protected endpoints require an authentication token sent via a custom HTTP header. This provides a simple yet effective security layer for local development.

Configuration​

Backend Setup​

Configure authentication in apps/backend/.env:

# Authentication Token (IMPORTANT: Change this!)
AUTH_TOKEN=your-secret-token-here

# Authentication Header Name (default: X-MCPGK-Token)
AUTH_TOKEN_HEADER_NAME=X-MCPGK-Token

Generating a Secure Token​

Generate a strong random token:

# Using openssl
openssl rand -hex 32

# Using Python
python3 -c "import secrets; print(secrets.token_hex(32))"

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Frontend Setup​

The frontend automatically reads the AUTH_TOKEN from the backend configuration when making API requests.

If you're using a custom token, ensure it matches the backend configuration.

How It Works​

Authentication Flow​

  1. Client sends HTTP request to protected endpoint
  2. Request includes X-MCPGK-Token header with the token
  3. Backend validates the token
  4. If valid, request proceeds; if invalid, returns 401 Unauthorized

Example Request​

curl -H "X-MCPGK-Token: your-secret-token-here" \
     http://127.0.0.1:8000/api/servers/

Protected Endpoints​

The following endpoints require authentication:

  • POST /api/servers/ - Create a new server
  • POST /api/servers/{id}/start - Start a server
  • POST /api/servers/{id}/stop - Stop a server
  • DELETE /api/servers/{id} - Delete a server
  • POST /api/packages/install-npm - Install a package
  • DELETE /api/packages/{id} - Uninstall a package
  • PUT /api/agents/{agent_type}/servers - Update agent config
  • DELETE /api/agents/{agent_type}/servers - Remove from agent config
  • DELETE /api/logs/ - Clear logs

Public Endpoints​

These endpoints do NOT require authentication:

  • GET /api/health - Health check
  • GET /api/servers/ - List servers
  • GET /api/servers/{id} - Get server details
  • GET /api/metrics/* - Get metrics
  • GET /api/logs/ - Get logs
  • GET /api/packages/ - List packages
  • GET /api/agents/ - List agents
  • WS /api/ws/metrics - WebSocket connection

Frontend Integration​

The frontend automatically includes the authentication token in requests:

// apps/frontend/src/services/api.ts
const API_TOKEN = 'your-token-here';

const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  headers: {
    'X-MCPGK-Token': API_TOKEN,
  },
});

Security Considerations​

Local-Only Access​

The backend binds to 127.0.0.1 (localhost) by default, preventing external network access:

# In apps/backend/.env
HOST=127.0.0.1

Do NOT change this to 0.0.0.0 unless you understand the security implications.

Token Storage​

  • Backend: Token stored in .env file (NOT committed to git)
  • Frontend: Token embedded in build (local development only)

Best Practices​

  1. Change Default Token: Always change the default token in production
  2. Use Strong Tokens: Generate tokens with at least 32 bytes of randomness
  3. Keep .env Secure: Never commit .env files to version control
  4. Rotate Tokens: Periodically change your authentication token
  5. Local-Only: Keep HOST=127.0.0.1 for local-only access

Troubleshooting​

401 Unauthorized Error​

If you receive a 401 error:

  1. Verify token in apps/backend/.env matches frontend
  2. Check that AUTH_TOKEN_HEADER_NAME is correct
  3. Ensure the token is included in the request header

Missing Authentication Token​

Error: Missing authentication token in 'X-MCPGK-Token' header

Solution: Include the token in your request headers.

Invalid Authentication Token​

Error: Invalid authentication token

Solution: Verify the token matches the AUTH_TOKEN in apps/backend/.env.

Custom Authentication​

Changing Header Name​

To use a different header name:

# In apps/backend/.env
AUTH_TOKEN_HEADER_NAME=X-Custom-Auth-Token

Update frontend accordingly:

// apps/frontend/src/services/api.ts
headers: {
  'X-Custom-Auth-Token': API_TOKEN,
}

Implementing OAuth/JWT​

For production deployments, consider implementing:

  • OAuth 2.0
  • JWT tokens
  • API key management
  • Rate limiting

See Development > Contributing for guidance on extending authentication.

Next Steps​