MCP Authentication

Configure authentication for MCP servers to secure access and enable token forwarding from upstream OAuth2 providers.

Authentication Methods

Static Token Authentication

The simplest authentication method using a pre-configured token:

[mcp.servers.api]
url = "https://api.example.com/mcp"

[mcp.servers.api.auth]
token = "bearer_token_here"
# Or use environment variables
token = "{{ env.API_TOKEN }}"

OAuth2 Token Forwarding

Forward the incoming OAuth2 token to downstream servers:

[mcp.servers.internal]
url = "https://internal.company.com/mcp"

[mcp.servers.internal.auth]
type = "forward"

Static Token Configuration

Basic Token

[mcp.servers.github]
url = "https://api.github.com/mcp"

[mcp.servers.github.auth]
token = "{{ env.GITHUB_TOKEN }}"

Bearer Token

[mcp.servers.api]
url = "https://api.example.com/mcp"

[mcp.servers.api.auth]
token = "Bearer {{ env.API_BEARER_TOKEN }}"

API Key

[mcp.servers.service]
url = "https://service.example.com/mcp"

[mcp.servers.service.auth]
token = "{{ env.SERVICE_API_KEY }}"

Token Forwarding

How It Works

  1. Client authenticates with Nexus using a JWT token
  2. Nexus validates the token using configured OAuth2 settings
  3. For servers with type = "forward", Nexus includes the same token in downstream requests
  4. Downstream servers validate the token independently

Configuration

# Enable OAuth2 on Nexus server
[server.oauth]
url = "https://auth.example.com/.well-known/jwks.json"
expected_issuer = "https://auth.example.com"
expected_audience = "nexus-api"

# Configure MCP server with token forwarding
[mcp.servers.protected_api]
url = "https://api.internal.com/mcp"

[mcp.servers.protected_api.auth]
type = "forward"

Requirements

  • OAuth2 must be enabled on the Nexus server
  • Downstream server must accept the same OAuth2 tokens
  • Both must use the same authorization server

Connection Caching

When using token forwarding, Nexus automatically caches connections per unique OAuth2 token to improve performance:

# Optional: Configure cache size and timeout
[mcp.downstream_cache]
max_size = 1000       # Max cached connections (default: 1000)
idle_timeout = "10m"  # Connection idle timeout (default: 10 minutes)
  • Static connections (no auth or static tokens) are created once at startup
  • Dynamic connections (token forwarding) are cached per unique user token
  • Connections are automatically evicted after the idle timeout

Use Cases

Token forwarding is ideal for:

  • Single Sign-On (SSO): One login for all tools
  • User Context: Maintain user identity across services
  • Audit Trail: Track actions by specific users
  • Multi-tenant Systems: Isolate data per user/tenant

Troubleshooting

401 Unauthorized:

  • Verify token is correct and not expired
  • Check token format (Bearer prefix if needed)
  • Ensure token has necessary permissions
  • Review server authentication logs

Token Forwarding Not Working:

  • Confirm OAuth2 is enabled on Nexus
  • Verify type = "forward" is set
  • Check downstream server accepts the tokens
  • Review token validation logs

Testing Authentication

# Test static token
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/mcp

Next Steps

© Grafbase, Inc.