MCP Server Configuration

Configure Model Context Protocol (MCP) servers to provide AI tools and capabilities through Nexus. MCP servers can be HTTP endpoints or local processes.

HTTP-based MCP servers implementing the latest protocol:

[mcp.servers.example]
url = "https://api.example.com/mcp"  # HTTP/HTTPS endpoint (required)
protocol = "streamable-http"          # Optional - auto-detected for HTTP URLs

# Optional authentication
[mcp.servers.example.auth]
token = "{{ env.API_TOKEN }}"         # Bearer token authentication

Local processes that communicate via standard input/output:

[mcp.servers.local_tool]
cmd = ["executable", "arg1", "arg2"]  # Command to execute (required)
env = { KEY = "value" }                # Environment variables (optional)
cwd = "/path/to/directory"             # Working directory (optional)
stderr = "null"                        # Error output handling (optional)

Server-Sent Events protocol (legacy - use Streamable HTTP when possible):

[mcp.servers.legacy]
protocol = "sse"                               # Must be "sse" (required)
url = "https://api.example.com/sse"           # SSE endpoint (required)
message_url = "https://api.example.com/msg"   # Message endpoint (optional)

# Optional authentication
[mcp.servers.legacy.auth]
token = "{{ env.API_TOKEN }}"

Configure custom headers for MCP server connections. Headers can be added to HTTP servers for authentication, tracking, or compatibility requirements:

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

# Add static headers to all server requests
[[mcp.servers.example.headers]]
rule = "insert"
name = "x-api-version"
value = "2024-01"

[[mcp.servers.example.headers]]
rule = "insert"
name = "x-client-id"
value = "{{ env.CLIENT_ID }}"  # Support for environment variables

You can also configure headers globally for all MCP servers:

# Global headers applied to all MCP servers
[[mcp.headers]]
rule = "insert"
name = "x-nexus-version"
value = "1.0.0"

[[mcp.headers]]
rule = "insert"
name = "x-environment"
value = "{{ env.ENVIRONMENT }}"

Note: MCP servers currently only support the insert rule for adding static headers. Headers are applied during connection initialization.

• url: The HTTP/HTTPS endpoint URL (required)

• protocol: Set to "streamable-http" (auto-detected for HTTP URLs)
• auth.token: Bearer token for authentication
• auth.type: Set to "forward" to forward OAuth2 tokens from clients
• headers: Array of header rules (currently only insert rule is supported)

• cmd: Command array with executable and arguments (required)

• env: Environment variables to set (default: {})
• cwd: Working directory for the subprocess (default: current directory)
• stderr: Where to send stderr output (default: "null")
  • "null": Discard stderr output
  • "inherit": Show in console
  • { file = "/path/to/log" }: Write to file

• protocol: Must be set to "sse" (required)
• url: The SSE endpoint URL (required)

• message_url: Separate endpoint for sending messages (defaults to url)
• auth.token: Bearer token for authentication

Use {{ env.VARIABLE_NAME }} for secure configuration management. Environment variables can be used in URLs, authentication tokens, command arguments, and environment settings.

You can configure multiple instances of the same MCP server type by using different names in your configuration. This is useful for connecting to different environments (dev/staging/prod) or multiple databases.

1. Use Descriptive Names: Choose names that clearly indicate the server's purpose

   [mcp.servers.code_search]  # Good
   [mcp.servers.server1]      # Bad

2. Group Related Servers: Use prefixes for related servers

   [mcp.servers.db_production]
   [mcp.servers.db_staging]
   [mcp.servers.db_development]

3. Avoid Special Characters: Stick to alphanumeric and underscores

   [mcp.servers.file_system]   # Good
   [mcp.servers."file.system"]  # Requires quotes

# Test command directly
$ /path/to/executable arg1 arg2

# Check environment variables
$ echo $GITHUB_TOKEN

# Test HTTP server
$ curl -I https://api.example.com/mcp

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

# Run Nexus with debug logs
$ nexus --log debug

Server not starting:

• Verify the executable path is correct
• Check file permissions (executable must have +x)
• Test the command manually in terminal
• Review stderr output (set stderr = "inherit")

Environment variables not working:

• Ensure variables are exported in your shell
• Check for typos in variable names
• Use echo to verify values

Connection failures:

• Verify the URL is accessible
• Check firewall rules
• Test with curl or similar tool
• Review TLS certificate configuration

Authentication errors:

• Verify API tokens are correct
• Check token format and headers
• Ensure tokens have necessary permissions

1. Security:

   • Always use environment variables for secrets
   • Never commit API keys to version control
   • Use TLS for HTTP connections
   • Restrict file system access in STDIO servers

2. Performance:

   • Keep STDIO commands lightweight
   • Use appropriate stderr handling (null in production)
   • Configure connection pooling for HTTP servers

3. Reliability:

   • Test servers individually before adding to Nexus
   • Implement health checks for critical servers
   • Use descriptive error messages
   • Log server initialization issues

4. Maintenance:

   • Document each server's purpose
   • Version control server configurations
   • Use consistent naming conventions
   • Keep server configurations modular

• Configure Authentication for secure access
• Set up TLS Configuration for encrypted connections
• Implement Rate Limiting for resource control