MCP Configuration

Configure Model Context Protocol (MCP) servers to provide tools and capabilities to AI models. MCP servers can be HTTP endpoints, local processes, or integrate with existing APIs.

Configuration Topics

Essential Configuration

  1. Server Configuration - Set up HTTP and STDIO MCP servers
  2. Authentication - Secure servers with tokens and OAuth2 forwarding
  3. TLS Configuration - Configure secure connections and certificates
  4. Rate Limiting - Control usage per server and tool

Quick Start

Basic Configuration

Enable MCP in your nexus.toml file:

[mcp]
enabled = true
path = "/mcp"

# HTTP-based MCP server
[mcp.servers.api]
url = "https://api.example.com/mcp"

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

# Add custom headers
[[mcp.servers.api.headers]]
rule = "insert"
name = "x-api-version"
value = "2024-01"

# Local STDIO server
[mcp.servers.filesystem]
cmd = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user"]

# Database tools
[mcp.servers.postgres]
cmd = ["psql-mcp"]
env = {
  PGHOST = "{{ env.DB_HOST }}",
  PGUSER = "{{ env.DB_USER }}",
  PGPASSWORD = "{{ env.DB_PASSWORD }}"
}

Server Types Overview

HTTP Servers

  • Streamable HTTP: Modern protocol with streaming support
  • SSE: Legacy Server-Sent Events (deprecated)
  • Support for authentication, TLS, and rate limiting

STDIO Servers

  • Local processes communicating via stdin/stdout
  • Perfect for local tools and scripts
  • Support for environment variables and working directories

Authentication Methods

Static Tokens

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

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

OAuth2 Token Forwarding

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

[mcp.servers.internal.auth]
type = "forward"  # Forward user's OAuth2 token

Complete Example

Here's a comprehensive configuration showing various MCP features:

[mcp]
enabled = true
path = "/mcp"

# Cache configuration for performance
[mcp.downstream_cache]
max_size = 1000
idle_timeout = "10m"

# Public API with rate limiting
[mcp.servers.weather]
url = "https://weather-api.example.com/mcp"

[mcp.servers.weather.rate_limits]
limit = 100
interval = "60s"

# Authenticated API with TLS
[mcp.servers.github]
url = "https://api.github.com/mcp"

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

[mcp.servers.github.tls]
verify_certs = true

# Tool-specific rate limits
[mcp.servers.github.rate_limits.tools]
search_code = { limit = 30, interval = "60s" }
create_issue = { limit = 10, interval = "60s" }

# Local database tools
[mcp.servers.database]
cmd = ["psql-mcp"]
env = {
  PGHOST = "localhost",
  PGDATABASE = "myapp",
  PGUSER = "{{ env.DB_USER }}",
  PGPASSWORD = "{{ env.DB_PASSWORD }}"
}
stderr = "null"  # Suppress stderr in production

# Internal service with OAuth2 forwarding
[mcp.servers.company_api]
url = "https://api.internal.company.com/mcp"

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

[mcp.servers.company_api.tls]
verify_certs = true
root_ca_cert_path = "/etc/ssl/company-ca.pem"

Key Features

  • Multiple Server Types: HTTP, STDIO, and SSE protocols
  • Flexible Authentication: Static tokens or OAuth2 forwarding
  • TLS Support: Including mutual TLS for high security
  • Rate Limiting: Per-server and per-tool limits
  • Connection Caching: Automatic caching for performance
  • Header Configuration: Add custom headers for authentication and tracking
  • Environment Variables: Secure configuration management

Best Practices

  1. Security First

    • Always use environment variables for secrets
    • Enable TLS verification in production
    • Use token forwarding only with trusted servers
    • Implement rate limiting for expensive operations

  2. Performance Optimization

    • Configure appropriate cache sizes
    • Use static connections when possible
    • Set reasonable rate limits
    • Monitor connection pool usage

  3. Operational Excellence

    • Test servers individually before deployment
    • Use descriptive server names
    • Document each server's purpose
    • Implement health checks

  4. Configuration Management

    • Separate configs for dev/staging/prod
    • Version control configurations
    • Never commit secrets
    • Validate before deployment

Common Use Cases

File System Access

[mcp.servers.fs]
cmd = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]

Database Operations

[mcp.servers.postgres]
cmd = ["psql-mcp"]
env = { PGHOST = "{{ env.DB_HOST }}" }

API Integration

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

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

Internal Tools

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

[mcp.servers.tools.auth]
type = "forward"  # Use user's OAuth2 token

Troubleshooting

Debug Mode

nexus --log debug

Common Issues

  • Connection failures: Check URLs and network access
  • Authentication errors: Verify tokens and permissions
  • Rate limit exceeded: Adjust limits or intervals
  • Cache misses: Increase cache size or timeout

Next Steps

© Grafbase, Inc.