Direct MCP Connection

Why use a direct connection?

By default, Claude Code and Claude Desktop connect to ArcLume through Anthropic's managed MCP proxy (mcp-proxy.anthropic.com). This works well most of the time, but the proxy is a single point of failure — if it goes down, all MCP tool access is unavailable even though ArcLume itself is healthy.

A direct connection lets your AI client talk to ArcLume's MCP endpoint without any intermediary. Use it:

• As a fallback when the Anthropic proxy is down
• For on-prem or air-gapped deployments where the Anthropic proxy is unreachable
• For lower latency — one fewer network hop

Prerequisites

You'll need an API key (prefix efk_) to authenticate direct connections. Generate one in Settings → API Keys in the ArcLume app.

Setup: Claude Code

Add the following to your .claude/mcp.json file (create it if it doesn't exist):

{
  "servers": {
    "arclume": {
      "type": "streamable-http",
      "url": "https://mcp.arclume.dev/mcp",
      "headers": {
        "Authorization": "Bearer efk_your_api_key_here"
      }
    }
  }
}

Replace efk_your_api_key_here with your actual API key. Restart Claude Code to pick up the new configuration.

Setup: Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "arclume": {
      "type": "streamable-http",
      "url": "https://mcp.arclume.dev/mcp",
      "headers": {
        "Authorization": "Bearer efk_your_api_key_here"
      }
    }
  }
}

Dev environment

If you're connecting to the development environment, use https://mcp.dev.arclume.dev/mcp instead.

How it works

The direct endpoint (mcp.arclume.dev) routes to the same ArcLume backend that powers the managed proxy connection. It supports the full MCP tool suite — maps, stories, outlines, codebase search, and library search. The only difference is the authentication method: direct connections use API keys instead of OAuth.

Available tools

All standard ArcLume MCP tools are available through the direct connection:

• Organization management — list orgs, set default
• Maps & stories — list, create, update, delete maps and stories
• Outlines — get and update map outlines
• Codebase search — keyword search across indexed repos
• Library — list documents, get content, semantic search across uploaded documents
• Repos — list connected repositories and indexing status

Troubleshooting

Authentication error

Verify your API key is valid and hasn't expired. You can check active keys in Settings → API Keys.

Connection refused

Ensure the URL is correct (https://mcp.arclume.dev/mcp) and your network allows outbound HTTPS. For corporate networks, you may need to allowlist the domain.

Tools not appearing

Restart your AI client after adding the configuration. Claude Code and Claude Desktop cache MCP server connections on startup.