Skip to content

MCP setup

agensai pair auto-writes MCP server config for the IDEs it detects. If auto-config didn't run, or you want to wire AGENSAI manually, this is the reference.

What gets configured

agensai is an MCP server. Over stdio, it exposes 10 tools that let your IDE manage the orchestrator's fleet: spawn agents, transfer tokens, run reads, revoke permissions. See Tools for the full list.

Each IDE has its own config location. The block AGENSAI writes is the same shape: a stdio MCP server invoked as npx -y agensai serve.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Add the agensai block:

{
  "mcpServers": {
    "agensai": {
      "command": "npx",
      "args": ["-y", "agensai", "serve"]
    }
  }
}

Restart Claude Desktop. The agent panel should show AGENSAI's 10 tools.

Cursor

Settings → MCP → Add new server.

{
  "mcpServers": {
    "agensai": {
      "command": "npx",
      "args": ["-y", "agensai", "serve"]
    }
  }
}

Or edit ~/.cursor/mcp.json directly.

Claude Code

From your terminal:

claude mcp add agensai npx -y agensai serve

Or edit your .claude/settings.json:

{
  "mcpServers": {
    "agensai": {
      "command": "npx",
      "args": ["-y", "agensai", "serve"]
    }
  }
}

Verify

Once config is in place and your IDE has been restarted, the agent panel / MCP server inspector should list agensai with its 10 tools. From the chat:

List my agents.

That call routes through the list_agents MCP tool. An empty list on a fresh pair is normal.

If the IDE can't connect, check:

  • agensai pair was run on this device and the orchestrator key exists at ~/.agensai/orchestrator.key.
  • npx agensai resolves on your PATH (some IDE sandboxes have a different PATH than your shell).
  • No stale lockfile at ~/.agensai/serve.lock is preventing startup.

Multi-IDE

You can wire AGENSAI to multiple IDEs simultaneously. Each will spawn its own MCP server attempt, but only one can hold the lockfile at a time. The first to call serve claims the lock; others fail with exit code 8.

In practice this means: your active IDE owns the MCP server. To switch, close the IDE that's holding it (or run agensai disconnect) before the other IDE's MCP client tries to start.

This is intentional. ERC-4337 nonces are per-account, so two MCP servers signing concurrently would collide. AGENSAI enforces single-active-device.

Self-hosted dashboard

If you're running the dashboard yourself (forked AGENSAI), pass the dashboard URL during pair:

npx agensai pair <token> --dashboard-url https://your-dashboard.example.com

After pairing, the MCP server needs no dashboard connection. It operates fully against the JAW stack from your device.