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. Authentication is per project — you will be connected to a specific Relevance AI project after logging in.

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.

Access control

When you authenticate via OAuth, the level of access your MCP session gets depends on your project role. Some roles have a fixed mode; others can opt in to a restriction.

Run-Only mode

Run-Only mode limits the MCP session to viewing and running existing agents. Write and destructive tools are removed from the tool list server-side — they are not present in the session at all, not merely hidden on the client. The OAuth consent screen shows a Run-Only mode toggle for Member, Editor, and Admin users. The toggle defaults to off (full access). Viewer and Chat users do not see the toggle — their access mode is fixed and cannot be changed.

Project role	MCP access mode	Configurable?
Admin	Full access	Yes — opt into run-only at OAuth consent
Editor	Full access	Yes — opt into run-only at OAuth consent
Member	Full access	Yes — opt into run-only at OAuth consent
Viewer	Run-only	No — forced, cannot disable
Chat	Chat mode	No — forced, cannot disable

To guarantee that a user’s MCP session cannot create, edit, or delete assets: assign them the Viewer or Chat project role. The restriction is enforced server-side regardless of which MCP client they use.

Chat role users cannot set up dynamic (user-level) OAuth connections via MCP. If an agent requires dynamic authentication, assign the user a Member role in a dedicated project instead.

MCP access is bounded by your project role — the API enforces a ceiling so a session never grants more than the role allows.

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

When triggering agents via MCP, you have two execution modes available depending on how long your agent takes to complete.

Execution modes

Synchronous
Asynchronous

The relevance_trigger_agent tool waits for the agent to finish and returns the result directly. It has a 120-second timeout, so use it for agents that complete quickly — single-step agents with minimal tool usage and no workforce nodes.

The relevance_trigger_agent_async and relevance_poll_agent_result tools work together with no timeout limit. The trigger returns immediately with a conversation ID, which you then poll to check status and retrieve results. Use this for agents with workforce nodes, multi-step chains, external API calls, or any execution expected to exceed 2 minutes.

If you encounter timeout errors with relevance_trigger_agent, switch to the async pattern. Agents with workforce nodes should always use async execution.

Async execution workflow

Trigger the agent

Call relevance_trigger_agent_async with your agent parameters. This returns immediately with a conversation_id.

Poll for results

Use relevance_poll_agent_result with the conversation_id to check the execution status. Poll every 3-5 seconds until the status is complete or failed.

Retrieve the results

The status will be working or in progress while the agent is executing, complete when results are available, or failed if an error occurred. Once complete, the poll response contains the agent’s output.

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

Agent execution timeouts

Timeout errors from relevance_trigger_agent mean your agent exceeded the 120-second synchronous limit. Switch to relevance_trigger_agent_async and relevance_poll_agent_result instead. See handling long-running agent executions for the full workflow. Agents with workforce nodes, multi-step chains, or complex workflows should always use the async pattern.

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?

Run-Only mode is the primary way to restrict MCP access. Assign a user the Viewer or Chat project role to force them into a restricted mode automatically — Viewers get run-only access (no write or destructive operations), and Chat users are limited to an even narrower set of tools. Member, Editor, and Admin users can opt into run-only mode from the toggle on the OAuth consent screen. For finer-grained control — such as exposing only a specific subset of agents — organize your tools across separate projects and authenticate each connection to the appropriate project. See Access control for the full role matrix.

Overview

Model Context Protocol

LLM Integrations

Popular Integrations

Integration Examples

Supported clients

Authentication

Working with multiple projects

Access control

Run-Only mode

Add agent skills

Handling long-running agent executions

Execution modes

Async execution workflow

Troubleshooting

Frequently asked questions (FAQs)

​Supported clients

​Authentication

​Working with multiple projects

​Access control

​Run-Only mode

​Add agent skills

​Handling long-running agent executions

​Execution modes

​Async execution workflow

​Troubleshooting

​Frequently asked questions (FAQs)

Supported clients

Authentication

Working with multiple projects

Access control

Run-Only mode

Add agent skills

Handling long-running agent executions

Execution modes

Async execution workflow

Troubleshooting

Frequently asked questions (FAQs)