mcp-server

Exposes Arc's core surfaces via the Model Context Protocol (MCP). External Claude Code instances, Cursor, or any MCP client can interact with Arc's task queue, skill tree, memory, and dispatch state.

Architecture

• Runtime: Bun + @modelcontextprotocol/sdk
• Transports: stdio (local, default) or HTTP (remote, --transport http)
• Auth: API key via --auth-key flag or mcp-server/auth_key credential (HTTP only)
• Database: Read/write to db/arc.sqlite via existing src/db.ts functions

Exposed Surfaces

Tools (read-write)

Resources (read-only)

CLI

arc skills run --name mcp-server -- start                          # stdio transport (default)
arc skills run --name mcp-server -- start --transport http         # HTTP on port 3100
arc skills run --name mcp-server -- start --port 3100 --auth-key KEY  # custom port + auth

When to Load

Load when: building or maintaining the MCP server itself, debugging connection issues, or adding new tools to the exposed surface. Do NOT load when using Arc as a dispatch agent — this skill is for managing the MCP server, not for tasks executed by external MCP clients.

Claude Code Integration

Add to .claude/settings.json (external client config, not Arc's own dispatch):

{
  "mcpServers": {
    "arc": {
      "command": "bun",
      "args": ["skills/arc-mcp-server/server.ts"],
      "alwaysLoad": true
    }
  }
}

alwaysLoad: true is recommended for external clients — it ensures tools are immediately available without a ToolSearch round-trip. Do NOT add arc-mcp-server to Arc's own .claude/settings.json; Arc uses the arc CLI directly during dispatch and does not connect to its own MCP surface.

For remote HTTP:

{
  "mcpServers": {
    "arc": {
      "url": "http://localhost:3100/mcp",
      "alwaysLoad": true
    }
  }
}

Timeout Configuration

External Claude Code clients connecting via HTTP transport should set MCP_TOOL_TIMEOUT for long-running resource operations:

export MCP_TOOL_TIMEOUT=120000  # 120 seconds (default: 60s)

This is primarily relevant for large MEMORY.md reads or extended cycle log queries. Arc's native tools (list_tasks, create_task, get_status) typically complete in <5 seconds. See Claude Code v2.1.142+ release notes for details on MCP_TOOL_TIMEOUT behavior.

Source: arc0btc/arc-starter — distributed by TomeVault.