Connect AI Apps to Roboto#

Overview#

This guide shows how to connect external AI applications (Claude Code, Claude Desktop, Codex, Cursor, and VS Code) to the Roboto MCP server, so the AI you already work in can search and analyze your Roboto data. For the underlying concepts, see Roboto MCP Server.

The server lives at:

https://mcp.roboto.ai/mcp

All clients use this one endpoint. In each setup below, you complete a one-time sign-in to Roboto in your browser; approve the connection to finish. A sign-in remains valid for up to 30 days.

Note

Private Roboto deployments host the server on their own domain. If your organization runs one, substitute its MCP address throughout.

Claude Code#

Add the server from a terminal:

claude mcp add --transport http roboto https://mcp.roboto.ai/mcp

Then, inside a Claude Code session, run /mcp and select roboto to complete the browser sign-in (or run claude mcp login roboto from your shell). Claude Code follows the server’s progress updates, so long-running analysis tools do not time out.

Claude Desktop#

  1. Go to Customize → Connectors, click +, and select Add custom connector.

  2. Enter the URL https://mcp.roboto.ai/mcp, then click Add.

  3. Roboto’s sign-in page opens in your browser; sign in and approve the connection. (If no window opens, click Connect on the new connector.)

Codex#

Add the server to ~/.codex/config.toml:

[mcp_servers.roboto]
url = "https://mcp.roboto.ai/mcp"

Then run codex mcp login roboto to complete the browser sign-in. In the Codex IDE extension, you can instead add the server under Settings → MCP servers → Add server, choosing Streamable HTTP.

Cursor#

Add the server to ~/.cursor/mcp.json (or a project’s .cursor/mcp.json):

{
  "mcpServers": {
    "roboto": {
      "url": "https://mcp.roboto.ai/mcp"
    }
  }
}

Then open Cursor’s MCP settings and click Needs login on the roboto entry to complete the browser sign-in.

VS Code#

Add the server to .vscode/mcp.json in your workspace, or to your user-profile mcp.json (via MCP: Add Server in the Command Palette, or by editing the file directly):

{
  "servers": {
    "roboto": {
      "type": "http",
      "url": "https://mcp.roboto.ai/mcp"
    }
  }
}

VS Code prompts you to authorize the server; approving the prompt opens the browser sign-in.

Connecting with an access token#

For non-interactive use (scripts, CI, or headless agents), skip the browser flow and authenticate with a personal access token in the Authorization header. For example, with Claude Code:

claude mcp add --transport http roboto https://mcp.roboto.ai/mcp \
  --header "Authorization: Bearer robo_pat_..."

Clients configured through mcp.json can send the same header — for example, in Cursor (VS Code’s servers entries take the same headers map):

{
  "mcpServers": {
    "roboto": {
      "url": "https://mcp.roboto.ai/mcp",
      "headers": {
        "Authorization": "Bearer robo_pat_..."
      }
    }
  }
}

Codex reads the token from an environment variable instead — name it in the server’s config.toml entry:

[mcp_servers.roboto]
url = "https://mcp.roboto.ai/mcp"
bearer_token_env_var = "ROBOTO_PAT"

The token must have full API access. Scope-restricted tokens are rejected because MCP tools read across the same API surface the token restricts.

Choose your organization#

If you belong to one organization, skip this section. If you belong to several, the first org-scoped tool call returns an error asking you to choose. Ask the AI:

  • “Who am I logged in as?” — the AI calls whoami and lists your organizations with their IDs.

  • “Use my Acme org” — the AI calls set_active_org, and the choice persists for 30 days from when you set it, across conversations and reconnects.

To pin an organization for a single call, tools also accept an optional org_id argument. Header-based setups can instead send X-Roboto-Org-Id alongside the Authorization header to fix the organization for every call.

Troubleshooting#

  • “You are a member of N orgs” errors — you haven’t chosen an active organization yet. Ask the AI to call whoami, then set_active_org.

  • A token is rejected — check that it hasn’t expired and that it has full API access; scope-restricted tokens are rejected.

  • A long analysis times out — some clients cap how long a single tool call may run (Claude Desktop currently enforces a few minutes, regardless of server progress updates). Narrow the analysis (the analysis tools accept optional scope_start_time / scope_end_time arguments that restrict them to a time window), or use Claude Code, which follows the server’s progress updates and by default lets a tool call run for hours.

  • Repeated sign-in prompts — a sign-in lasts up to 30 days; a prompt before that usually means the client’s stored sign-in state is stale. Remove and re-add the server to reset it, then sign in again.

On this page