MCP server

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/

For Claude Code, we recommend using the Relevance AI plugin instead of a manual MCP connection — it includes built-in skills and context that make the experience significantly better.

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.

Supported clients

Claude Desktop

Open Claude Desktop
Go to Settings → Connectors
Click Add connector
Enter the server URL: https://mcp.relevanceai.com/
Follow the authentication prompts to connect your Relevance AI project

Claude Web

Navigate to the Connectors page in Claude.ai
Click Add connector
Enter the server URL: https://mcp.relevanceai.com/
Follow the authentication prompts

ChatGPT

ChatGPT supports MCP servers through Developer Mode, available on Pro, Team, Enterprise, and Edu plans.

Open ChatGPT Settings
Go to Connectors → Advanced → Developer Mode
Click Add connector
Enter the server URL: https://mcp.relevanceai.com/
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.

Cursor

Open Cursor Settings
Navigate to the MCP tab
Click Add new MCP server
Use the following configuration in your mcp.json:

{
  "mcpServers": {
    "relevance-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
    }
  }
}

VS Code / Copilot

Add the following to your VS Code settings (.vscode/mcp.json):

{
  "mcpServers": {
    "relevance-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
    }
  }
}

Windsurf

Add the following to your Windsurf MCP configuration:

{
  "mcpServers": {
    "relevance-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
    }
  }
}

Codex

codex mcp add relevance-ai --url https://mcp.relevanceai.com/
codex mcp login relevance-ai

See the OpenAI Codex page for the full setup, including cloning the agent skills.

Zed

Add the following to your Zed settings (settings.json):

{
  "language_models": {
    "mcp": {
      "servers": {
        "relevance-ai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
        }
      }
    }
  }
}

v0 by Vercel

Add the following MCP configuration in your v0 project settings:

{
  "mcpServers": {
    "relevance-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.relevanceai.com/"]
    }
  }
}

Claude Code (manual)

If you prefer to add the MCP server directly without the plugin:

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.

Other clients

For any MCP-compatible client, use the server URL:

https://mcp.relevanceai.com/

If your client requires an npx command, use:

npx -y mcp-remote https://mcp.relevanceai.com/

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. 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:

{
  "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/"]
    }
  }
}

{
  "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/"]
    }
  }
}

{
  "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/"]
    }
  }
}

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.

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.

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 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

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.

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.

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.

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.

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.

For workforces, version_id pins the graph topology only — nested agents still run their latest version.

Cancelling executions

Three tools stop in-progress work:

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.

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.

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.

Troubleshooting

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

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

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

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.

Frequently asked questions (FAQs)

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.

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.

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.

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.

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.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.

Overview

Model Context Protocol

LLM Integrations

Popular Integrations

Integration Examples

Supported clients

Authentication

Roles and access levels

Working with multiple projects

Add agent skills

Handling long-running agent executions

Execution workflow

Running evaluations

Cancelling executions

Troubleshooting

Frequently asked questions (FAQs)

​Supported clients

​Authentication

​OAuth consent and access control

​Roles and access levels

​Working with multiple projects

​Add agent skills

​Handling long-running agent executions

​Execution workflow

​Running evaluations

​Cancelling executions

​Troubleshooting

​Frequently asked questions (FAQs)

Supported clients

Authentication

OAuth consent and access control

Roles and access levels

Working with multiple projects

Add agent skills

Handling long-running agent executions

Execution workflow

Running evaluations

Cancelling executions

Troubleshooting

Frequently asked questions (FAQs)