Using Nexus with Claude Code

Nexus supports the Anthropic protocol natively, allowing you to use it as a proxy for Claude Code. This enables you to leverage Nexus's features like rate limiting, observability, MCP aggregation, and multi-provider routing while using Claude Code.

• Nexus v0.5.0 or later (with Anthropic protocol support)
• An Anthropic API key
• Claude Code installed and configured

Update your nexus.toml to enable the Anthropic protocol and configure the provider:

[llm]
enabled = true

# Enable the Anthropic protocol endpoint
[llm.protocols.anthropic]
enabled = true
path = "/llm/anthropic"  # This is the default path

# Configure the Anthropic provider
[llm.providers.anthropic]
type = "anthropic"
api_key = "{{ env.ANTHROPIC_API_KEY }}"
# Optional: Use a custom base URL (defaults to https://api.anthropic.com/v1)
# base_url = "https://api.anthropic.com/v1"

# Configure the models you want to use
[llm.providers.anthropic.models."claude-sonnet-4-20250514"]
[llm.providers.anthropic.models."claude-3-5-haiku-latest"]
[llm.providers.anthropic.models."claude-opus-4-1-20250805"]

Set your Anthropic API key:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

nexus --config nexus.toml

By default, Nexus will listen on http://localhost:6000.

Set environment variables to point Claude Code to your Nexus instance:

# Point Claude Code to your Nexus instance
export ANTHROPIC_BASE_URL="http://localhost:6000/llm/anthropic"

# Specify the model with the provider prefix
export ANTHROPIC_MODEL="anthropic/claude-3-5-sonnet-20241022"

Now you can use Claude Code normally, and all requests will be routed through Nexus:

claude "Explain how to implement a binary search tree"

You can configure other language models, for example OpenAI GPT-5 to work with Claude Code:

[llm]
enabled = true

[llm.protocols.anthropic]
enabled = true
path = "/llm/anthropic"

[llm.providers.openai]
type = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"

[llm.providers.openai.models."gpt-5"]

Set environment variables to point Claude Code to your Nexus instance:

# Point Claude Code to your Nexus instance
export ANTHROPIC_BASE_URL="http://localhost:6000/llm/anthropic"

# Specify the model with the provider prefix
export ANTHROPIC_MODEL="openai/gpt-5"

If you're running Nexus in Docker:

services:
  nexus:
    image: ghcr.io/grafbase/nexus:latest
    ports:
      - "6000:6000"
    volumes:
      - ./nexus.toml:/etc/nexus.toml
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

Then configure Claude Code to use the containerized Nexus:

export ANTHROPIC_BASE_URL="http://localhost:6000/llm/anthropic"
export ANTHROPIC_MODEL="anthropic/claude-3-5-sonnet-20241022"

Using Nexus with Claude Code provides:

1. Unified Gateway: Route all AI requests through a single endpoint
2. Rate Limiting: Control token consumption per user and model
3. Observability: Built-in OpenTelemetry metrics, traces, and logs
4. Multi-Provider Support: Switch between providers without changing Claude Code configuration
5. Model Management: Configure and manage models centrally
6. Security: Add authentication, CORS, and CSRF protection
7. Cost Control: Monitor and limit token usage

The Anthropic protocol implementation in Nexus:

• Fully supports Claude Code's mixed content format (strings and arrays)
• Handles tool calling and function definitions
• Supports streaming responses

If Claude Code can't connect to Nexus:

1. Verify Nexus is running:

   curl http://localhost:6000/health

2. Check the Anthropic protocol is enabled:

   curl http://localhost:6000/llm/anthropic/v1/models

3. Verify environment variables:

   echo $ANTHROPIC_BASE_URL
   echo $ANTHROPIC_MODEL

If you get a "model not found" error:

1. Ensure the model is configured in nexus.toml
2. Use the correct format: anthropic/model-name
3. List available models:

   curl http://localhost:6000/llm/anthropic/v1/models

If you get authentication errors:

1. Verify your API key is set correctly:

   echo $ANTHROPIC_API_KEY

2. Check Nexus logs for more details:

   nexus --log debug

In addition to using Nexus as an LLM proxy, you can also connect Claude Code to Nexus's MCP (Model Context Protocol) server to access all the tools aggregated by Nexus.

First, ensure MCP is enabled in your nexus.toml and configure your MCP servers:

[mcp]
enabled = true
path = "/mcp"  # Default MCP endpoint

# Example: Add GitHub MCP server
[mcp.servers.github]
url = "https://api.githubcopilot.com/mcp/"
auth.token = "{{ env.GITHUB_TOKEN }}"

# Example: Add filesystem MCP server
[mcp.servers.filesystem]
cmd = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/YOUR_USERNAME/Desktop"]

# Example: Add a Python MCP server
[mcp.servers.python_server]
cmd = ["python", "-m", "mcp_server"]
env = { PYTHONPATH = "/opt/mcp" }
cwd = "/workspace"

Use the Claude CLI to add Nexus as an MCP server:

claude mcp add nexus http://localhost:6000/mcp --transport http

After adding the MCP server, verify the connection:

claude mcp list

Once connected, Claude Code can access all tools aggregated by Nexus through two main functions:

1. Search for tools: Claude can search across all connected MCP servers
2. Execute tools: Claude can execute specific tools with parameters

Example interaction:

claude "Use the filesystem tool to list files in my Desktop"
# Claude will search for, and execute the filesystem tool through Nexus

Here's a complete example setting up both LLM proxy and MCP server:

# 1. Start Nexus with both LLM and MCP configured
nexus --config nexus.toml

# 2. Configure Claude Code to use Nexus as LLM proxy
export ANTHROPIC_BASE_URL="http://localhost:6000/llm/anthropic"
export ANTHROPIC_MODEL="anthropic/claude-3-5-sonnet-20241022"

# 3. Add Nexus MCP server to Claude Code
claude mcp add nexus http://localhost:6000/mcp --transport http

# 4. Verify both connections
claude mcp test nexus
claude "Hello, can you see my MCP tools?"

1. Tool Aggregation: Access all your MCP servers through a single endpoint
2. Intelligent Search: Nexus provides context-aware fuzzy search across all tools
3. Unified Management: Configure all MCP servers in one place (nexus.toml)
4. Authentication: Nexus handles authentication to downstream MCP servers
5. Observability: Monitor all MCP tool usage through Nexus's telemetry

If Claude Code can't connect to Nexus MCP:

1. Verify Nexus is running and MCP is enabled:

   curl http://localhost:6000/mcp

2. Check Claude Code's MCP configuration:

   claude mcp list

3. Test the connection directly:

   claude mcp test nexus

4. Check Nexus logs for MCP requests:

   nexus --log debug

• Configure MCP Servers in Nexus
• Set up Rate Limiting to control usage
• Configure Telemetry for observability
• Explore Header Rules for advanced routing
• Learn about Token Forwarding to let users provide their own API keys