Server Configuration

This guide covers how to configure the Nexus server, including network settings, security features, and OAuth2 authentication with token forwarding.

Configure the core server behavior in your nexus.toml:

[server]
listen_address = "127.0.0.1:8000"

[server.health]
enabled = true
path = "/health"

• listen_address: The address and port Nexus will bind to (optional, defaults to system assignment)
• health.enabled: Enable the health check endpoint (default: true)
• health.path: Path for health checks (default: /health)
• health.listen: Separate address for health endpoint (optional)

For secure connections, configure TLS certificates:

[server.tls]
certificate = "/path/to/server.crt"
key = "/path/to/server.key"

Both certificate and key must be in PEM format.

Nexus provides comprehensive OAuth2 support for securing your MCP endpoints. This is crucial for production deployments where you need to control access to your AI tools.

Configure OAuth2 authentication in your nexus.toml:

[server.oauth]
url = "https://your-auth-provider.com/.well-known/jwks.json"
poll_interval = "5m"
expected_issuer = "https://your-auth-provider.com"
expected_audience = "your-nexus-instance"

[server.oauth.protected_resource]
resource = "https://nexus.example.com"
authorization_servers = ["https://your-auth-provider.com"]

• url: The JWKS (JSON Web Key Set) endpoint URL for validating JWT tokens (required)
• poll_interval: How often to refresh the JWKS (optional, format: "5m", "1h", etc.)
• expected_issuer: The expected iss claim in JWT tokens (optional but recommended)
• expected_audience: The expected aud claim in JWT tokens (optional but recommended)

• protected_resource.resource: The URL of this Nexus instance as a protected resource (required)
• protected_resource.authorization_servers: List of trusted authorization server URLs (required)

The protected resource metadata is exposed at /.well-known/oauth-protected-resource as per RFC-9728.

When OAuth2 is enabled:

1. All endpoints require authentication (except /health and /.well-known/oauth-protected-resource)
2. JWT tokens are validated using the configured JWKS endpoint
3. Token claims are verified against expected issuer and audience
4. Access is granted or denied based on token validity

[server.oauth]
url = "https://your-tenant.auth0.com/.well-known/jwks.json"
poll_interval = "15m"
expected_issuer = "https://your-tenant.auth0.com/"
expected_audience = "https://nexus.your-domain.com"

[server.oauth.protected_resource]
resource = "https://nexus.your-domain.com"
authorization_servers = ["https://your-tenant.auth0.com/"]

[server.oauth]
url = "https://your-domain.okta.com/oauth2/default/v1/keys"
poll_interval = "10m"
expected_issuer = "https://your-domain.okta.com/oauth2/default"
expected_audience = "api://nexus"

[server.oauth.protected_resource]
resource = "https://nexus.your-domain.com"
authorization_servers = ["https://your-domain.okta.com/oauth2/default"]

One of Nexus's powerful features is the ability to forward OAuth2 tokens to downstream MCP servers. This enables seamless authentication across your entire AI infrastructure.

Use token forwarding when:

• Your downstream MCP servers use the same OAuth2 provider
• You want single sign-on (SSO) across all tools
• You need to maintain user context through the entire request chain

For each MCP server that should receive the forwarded token:

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

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

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
5. These dynamic connections are cached per unique token (see cache configuration details)

Configure Cross-Origin Resource Sharing (CORS) for browser-based clients:

[server.cors]
allow_origins = ["https://app.example.com", "http://localhost:3000"]
allow_methods = ["GET", "POST"]
allow_headers = ["authorization", "content-type", "x-request-id"]
allow_credentials = true
max_age = 3600
allow_private_network = false
expose_headers = ["x-request-id", "x-trace-id"]

• allow_origins: List of allowed origins, a single origin, or "*" for all origins
• allow_methods: HTTP methods to allow (can be array or "*")
• allow_headers: Headers that clients can send (can be array or "*")
• allow_credentials: Whether to allow credentials in CORS requests (default: false)
• max_age: How long browsers can cache CORS preflight responses (in seconds)
• allow_private_network: Allow requests from private networks (default: false)
• expose_headers: Headers to expose to the client (can be array or "*")

For allow_origins, allow_methods, allow_headers, and expose_headers, you can use:

• An array of specific values: ["value1", "value2"]
• A single value: "value"
• Wildcard to allow all: "*"

Configure CSRF (Cross-Site Request Forgery) protection:

[server.csrf]
enabled = true
header_name = "X-CSRF-Token"

• enabled: Whether CSRF protection is enabled (default: false)
• header_name: The header name to use for CSRF tokens (default: "X-Nexus-CSRF-Protection")

When enabled, Nexus will require this header to be present on state-changing requests.

Nexus provides rate limiting capabilities to protect your server from abuse and ensure fair resource usage. You can configure global and per-IP rate limits at the server level.

Enable rate limiting in your nexus.toml:

[server.rate_limits]
enabled = true
storage = "memory"  # or use Redis for distributed rate limiting

[server.rate_limits.global]
limit = 1000
interval = "60s"

[server.rate_limits.per_ip]
limit = 100
interval = "60s"

• enabled: Enable or disable rate limiting (default: false)
• storage: Storage backend - either "memory" (default) or a Redis configuration

Global Limits (server.rate_limits.global)

• limit: Maximum requests across all clients
• interval: Time window (e.g., "60s", "5m", "1h")

Per-IP Limits (server.rate_limits.per_ip)

• limit: Maximum requests per IP address
• interval: Time window

Uses an in-memory rate limiter, suitable for single-instance deployments:

[server.rate_limits]
storage = "memory"

For distributed rate limiting across multiple Nexus instances:

[server.rate_limits]
storage = { type = "redis", url = "redis://localhost:6379" }

Redis configuration options:

• url: Redis connection URL (default: "redis://localhost:6379/0")
• key_prefix: Prefix for rate limit keys (default: "nexus:rate_limits:")
• pool.max_size: Maximum connection pool size (default: 16)
• pool.min_idle: Minimum idle connections (default: 0)
• pool.timeout_create: Timeout for creating connections (optional)
• pool.timeout_wait: Timeout for waiting for a connection (optional)
• pool.timeout_recycle: Timeout for recycling connections (optional)
• tls.enabled: Enable TLS connection (default: false)
• tls.insecure: Skip TLS certificate verification (optional)
• tls.ca_cert_path: Path to CA certificate (optional)
• tls.client_cert_path: Path to client certificate (optional)
• tls.client_key_path: Path to client private key (optional)
• response_timeout: Timeout for Redis responses (optional)
• connection_timeout: Timeout for Redis connections (optional)

Full Redis example:

[server.rate_limits]
storage = {
  type = "redis",
  url = "redis://username:password@redis.example.com:6379/0",
  key_prefix = "nexus:rate_limits:prod:",
  response_timeout = "10s",
  connection_timeout = "10s"
}

# With connection pool configuration
[server.rate_limits.storage.pool]
max_size = 20
min_idle = 5
timeout_create = "5s"
timeout_wait = "5s"

# With TLS configuration
[server.rate_limits.storage.tls]
enabled = true
ca_cert_path = "/etc/ssl/certs/redis-ca.pem"

When a client exceeds the rate limit, Nexus responds with:

• HTTP status code 429 Too Many Requests
• Retry-After header indicating when the client can retry (in seconds)

For more granular control, including per-MCP-server and per-tool rate limits, see the MCP configuration documentation.

401 Unauthorized Errors

• Verify the JWT token is valid and not expired
• Check that the JWKS URL is accessible
• Ensure expected claims match token contents
• Verify the Authorization: Bearer <token> header is present

Token Forwarding Not Working

• Confirm type = "forward" is set for the server
• Verify the downstream server accepts the same tokens
• Check server logs for authentication errors
• Ensure OAuth2 is enabled on the Nexus server

JWKS Refresh Issues

• Ensure the JWKS URL is reachable from Nexus
• Check network connectivity and firewall rules
• Verify the poll_interval format is correct (e.g., "5m", "1h")

Preflight Failures

• Ensure OPTIONS is included in allow_methods
• Check that required headers are in allow_headers
• Verify the origin is in allow_origins

Credentials Not Working

• Set allow_credentials = true
• Ensure the origin is explicitly listed (not using "*")

• Configure your MCP servers
• Set up AI assistant integration