> ## Documentation Index
> Fetch the complete documentation index at: https://relevanceai-docs-consolidate-mcp-server.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect to Relevance AI from Claude Desktop, Cursor, VS Code, ChatGPT, and other MCP-compatible AI clients.

The Relevance AI MCP server gives any MCP-compatible AI client direct access to your agents, tools, and knowledge. Connect from the AI tools you already use and start building.

The MCP server is available at:

```
https://mcp.relevanceai.com/
```

<Tip>For Claude Code, we recommend using the [Relevance AI plugin](/integrations/mcp/claude-code) instead of a manual MCP connection — it includes built-in skills and context that make the experience significantly better.</Tip>

<Warning>
  This page is about using Relevance AI **from** external AI clients. If you want to connect an external MCP server **to** a Relevance AI agent, see [MCP Client](/integrations/mcp/mcp-client).
</Warning>

***

## Supported clients

<AccordionGroup>
  <Accordion title="Claude Desktop" icon="message-bot">
    1. Open Claude Desktop
    2. Go to **Settings** → **Connectors**
    3. Click **Add connector**
    4. Enter the server URL: `https://mcp.relevanceai.com/`
    5. Follow the authentication prompts to connect your Relevance AI project
  </Accordion>

  <Accordion title="Claude Web" icon="globe">
    1. Navigate to the [Connectors page](https://claude.ai/settings/connectors) in Claude.ai
    2. Click **Add connector**
    3. Enter the server URL: `https://mcp.relevanceai.com/`
    4. Follow the authentication prompts
  </Accordion>

  <Accordion title="ChatGPT" icon="comment">
    ChatGPT supports MCP servers through Developer Mode, available on Pro, Team, Enterprise, and Edu plans.

    1. Open ChatGPT **Settings**
    2. Go to **Connectors** → **Advanced** → **Developer Mode**
    3. Click **Add connector**
    4. Enter the server URL: `https://mcp.relevanceai.com/`
    5. Set Authentication to **OAuth** and follow the login flow

    Once connected, the Relevance AI tools will be available in both Chat and Deep Research modes.
  </Accordion>

  <Accordion title="Cursor" icon="i-cursor">
    1. Open Cursor Settings
    2. Navigate to the **MCP** tab
    3. Click **Add new MCP server**
    4. Use the following configuration in your `mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "relevance-ai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VS Code / Copilot" icon="code">
    Add the following to your VS Code settings (`.vscode/mcp.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "relevance-ai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Windsurf" icon="wind">
    Add the following to your Windsurf MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "relevance-ai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Codex" icon="robot">
    Register the MCP server, then log in:

    ```bash theme={null}
    codex mcp add relevance-ai --url https://mcp.relevanceai.com/
    codex mcp login relevance-ai
    ```

    See the [OpenAI Codex](/integrations/mcp/codex) page for the full setup, including cloning the agent skills.
  </Accordion>

  <Accordion title="Zed" icon="pen-nib">
    Add the following to your Zed settings (`settings.json`):

    ```json theme={null}
    {
      "language_models": {
        "mcp": {
          "servers": {
            "relevance-ai": {
              "command": "npx",
              "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="v0 by Vercel" icon="bolt">
    Add the following MCP configuration in your v0 project settings:

    ```json theme={null}
    {
      "mcpServers": {
        "relevance-ai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Claude Code (manual)" icon="terminal">
    If you prefer to add the MCP server directly without the plugin:

    ```bash theme={null}
    claude mcp add relevance-prod --transport http https://mcp.relevanceai.com/
    ```

    Once added, run `/mcp` from within Claude Code. You will see the new MCP server in the list. Select it to connect and follow the authentication steps.
  </Accordion>

  <Accordion title="Other clients" icon="plug">
    For any MCP-compatible client, use the server URL:

    ```
    https://mcp.relevanceai.com/
    ```

    If your client requires an `npx` command, use:

    ```bash theme={null}
    npx -y mcp-remote https://mcp.relevanceai.com/
    ```
  </Accordion>
</AccordionGroup>

***

## Authentication

When you first connect, you will be prompted to authenticate with your Relevance AI account via an OAuth consent page. Authentication is **per project** — you will be connected to a specific Relevance AI project after logging in.

### OAuth consent and access control

The OAuth consent page lets you review the access being granted to the connecting AI client before completing authentication. It includes a **Run-only access** toggle that controls what the connected AI agent can do within your project.

When run-only access is enabled, the connected AI agent can view and execute agents, tools, and workforces — but write and delete tools are entirely absent from the MCP tool list, not just blocked. The agent cannot create, edit, publish, or delete any assets. When run-only access is disabled, the agent has the same capabilities your account role allows.

### Roles and access levels

Your project role determines the default access mode and whether you can change it:

| Role                    | Can connect via MCP | Default mode | Can toggle run-only |
| ----------------------- | ------------------- | ------------ | ------------------- |
| Viewer                  | ✅                   | Run-only     | ❌ (locked)          |
| Member / Editor / Admin | ✅                   | Full access  | ✅                   |

Viewer-role users are always placed in run-only mode — the toggle is locked for them and cannot be changed. Users with Member, Editor, or Admin roles connect in full access mode by default, but can enable run-only access voluntarily on the consent page to limit what the connected AI agent can do.

### Working with multiple projects

If you work across multiple Relevance AI projects, add a separate MCP server entry for each:

<CodeGroup>
  ```json Cursor theme={null}
  {
    "mcpServers": {
      "relevance-project-1": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      },
      "relevance-project-2": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      }
    }
  }
  ```

  ```json VS Code theme={null}
  {
    "mcpServers": {
      "relevance-project-1": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      },
      "relevance-project-2": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      }
    }
  }
  ```

  ```json Windsurf theme={null}
  {
    "mcpServers": {
      "relevance-project-1": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      },
      "relevance-project-2": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
      }
    }
  }
  ```
</CodeGroup>

Each entry authenticates independently against its own project, so you can access tools and agents across all your projects without logging out and back in.

<Note>
  Alternatively, you can use a single connection and log out / log back in to switch projects — but the multi-connection approach above is preferred for convenience.
</Note>

***

## Add agent skills

The MCP server gives your AI assistant the ability to call Relevance AI tools, but it doesn't know *how* to use them well. For better results, pair it with the [agent skills](/integrations/mcp/agent-skills) repository — a local reference that teaches your assistant how to work with agents, tools, workforces, knowledge, and more.

***

## Handling long-running agent executions

Triggering an agent via MCP never blocks on the agent finishing. `relevance_trigger_agent` returns immediately, and you poll for the result separately — so the pattern is the same whether an agent takes two seconds or twenty minutes.

### Execution workflow

<Steps>
  <Step title="Trigger the agent">
    Call `relevance_trigger_agent` with the agent ID and your message. It returns immediately with a `conversation_id` — the same value other agent task tools call `task_id`. It does not wait for the agent to finish.
  </Step>

  <Step title="Poll for results">
    Call `relevance_poll_agent_result` with the `agent_id` and `conversation_id`. Pass `wait_seconds` to long-poll until the run reaches a terminal state — the default window is 50 seconds and the maximum is 300. Pass `0` for a single-shot check.
  </Step>

  <Step title="Read the status">
    `in_progress` means keep polling. `completed` means the response contains the agent's output. `failed` means the agent itself terminated. `pending_approval` means a human needs to act — the response includes the conversation URL to visit.
  </Step>
</Steps>

<Note>
  If a tool errored but the agent recovered, the status stays `completed` or `in_progress` and the response includes `had_recoverable_tool_errors: true`. That flag reflects only the most recent messages inspected, so treat its presence as a positive signal and not its absence as proof no tool ever failed.
</Note>

### Running evaluations

`relevance_run_evaluation` starts an evaluation run against an agent or workforce, so you can score changes without leaving your AI client.

| Parameter             | Required | Description                                                                 |
| --------------------- | -------- | --------------------------------------------------------------------------- |
| `resource_type`       | Yes      | Either `agent` or `workforce`                                               |
| `resource_id`         | Yes      | The agent or workforce ID to evaluate                                       |
| `evaluation_run_name` | Yes      | A name for this run                                                         |
| `test_set_id`         | No       | Test set to run every scenario from. Mutually exclusive with `scenario_ids` |
| `scenario_ids`        | No       | Ad-hoc scenario IDs to run. Mutually exclusive with `test_set_id`           |
| `version_id`          | No       | A specific version to evaluate. Omit to use the active published version    |

Pass either `test_set_id` or `scenario_ids`, not both. Poll for the outcome with `relevance_poll_eval_batch_result`, and stop a run in progress with `relevance_cancel_eval_batch`.

<Note>
  For workforces, `version_id` pins the graph topology only — nested agents still run their latest version.
</Note>

### Cancelling executions

Three tools stop in-progress work:

<AccordionGroup>
  <Accordion title="relevance_cancel_agent_task">
    Cancels a running agent task. Pass `task_id` — the `conversation_id` returned by `relevance_trigger_agent`. New turns are blocked and the run halts at its next step boundary: the in-flight step finishes first, so there is no hard abort mid-step. The task stays stopped.
  </Accordion>

  <Accordion title="relevance_cancel_workforce_task">
    Cancels a running workforce task, halting routing and signalling the running step to stop. Pass both `workforce_id` and `task_id`.
  </Accordion>

  <Accordion title="relevance_cancel_tool_run">
    Cancels a single in-flight tool run on a best-effort basis. Pass `task_id`, the run ID from `relevance_list_tool_runs`.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication issues">
    * Make sure you have an active Relevance AI account
    * Check that you have access to the project you are trying to connect to
    * Try removing and re-adding the MCP server connection
  </Accordion>

  <Accordion title="Tools not appearing">
    * Verify that you have tools configured in your Relevance AI project
    * Check that you are authenticated to the correct project
    * Try disconnecting and reconnecting the MCP server
  </Accordion>

  <Accordion title="Connection errors">
    * Ensure you have a stable internet connection
    * Check that `https://mcp.relevanceai.com/` is accessible from your network
    * Try removing and re-adding the MCP server connection in your client
    * Try clearing the auth cache: `rm -rf ~/.mcp-auth`
  </Accordion>

  <Accordion title="An agent run never seems to finish">
    `relevance_trigger_agent` returns as soon as the run starts, so a long-running agent is expected rather than a timeout. Poll with `relevance_poll_agent_result` and a `wait_seconds` window (up to 300) until the status becomes `completed`, `failed`, or `pending_approval` — `in_progress` means keep polling. A run sitting at `pending_approval` is waiting on a human, not stuck; the poll response includes the conversation URL to visit. To stop a run outright, see [cancelling executions](#cancelling-executions).
  </Accordion>
</AccordionGroup>

***

## Frequently asked questions (FAQs)

<AccordionGroup>
  <Accordion title="What is MCP?">
    The Model Context Protocol (MCP) is an open standard that allows AI clients to connect to external tools and data sources. It provides a standardized way for AI assistants to access your Relevance AI workspace.
  </Accordion>

  <Accordion title="Is the MCP server free to use?">
    The MCP server itself is free. You will be billed for any Relevance AI usage (agent runs, tool executions, etc.) according to your plan.
  </Accordion>

  <Accordion title="Can I use multiple AI clients at the same time?">
    Yes. You can connect to the Relevance AI MCP server from as many clients as you like simultaneously. Each client authenticates independently.
  </Accordion>

  <Accordion title="Does authentication expire?">
    Authentication tokens may expire after a period of inactivity. If you are prompted to re-authenticate, simply follow the login flow again.
  </Accordion>

  <Accordion title="Can I restrict which tools are available via MCP?">
    There are two ways to restrict MCP tool access.

    The first is the **Run-only access** toggle on the OAuth consent page. When enabled, write and delete tools are entirely absent from the MCP tool list, so the connected AI agent can only view and execute assets. Viewer-role users are placed in run-only mode automatically. See [OAuth consent and access control](#oauth-consent-and-access-control).

    The second is project separation. The MCP server exposes the tools and agents available in the project you authenticated against, so you can organize tools across different projects and authenticate each connection to the appropriate one.
  </Accordion>
</AccordionGroup>