---
title: Use the Roboto MCP Server
sidebar:
  order: 33
---
## 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](/docs/learn/ai/mcp-server).

The server lives at:

```text
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:

```bash
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`:

```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`):

```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):

```json
{
  "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](/docs/getting-started/programmatic-access#access-token-section) in the `Authorization` header. For example, with Claude Code:

```bash
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):

```json
{
  "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:

```toml
[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.