Relevance AI API, SDK and MCP Server: A Developer Setup Guide

Relevance AI gives developers three ways in: a regional REST API that starts agents and tools, a JavaScript/TypeScript SDK (@relevanceai/sdk) for messaging agents and following their tasks, and an MCP server at mcp.relevanceai.com that lets coding agents such as Claude Code build and run agents for you. The limit to know first sits on the API side. Relevance AI officially supports its API only for triggering Agents and Tools, and the trigger call does not hand the agent's answer back to you ^[1]. So the SDK fits apps that need the reply, and MCP fits teams that want a coding agent to do the building.

None of this works on an empty account. Every organization now needs a paid plan, and Relevance AI's pricing pages describe no free trial. The MCP server itself costs nothing, but every agent run and tool execution it starts is billed on your plan, exactly as runs started from the app are. Test runs that execute a Tool count as Actions too. Budget for them.

Three doors into Relevance AI, and which one to open

The docs draw the line between the first two fairly clearly. They suggest the SDK for embedding agent chat in a web or mobile app, triggering agents from a backend or a cron job, and running workforces from a server-side pipeline. For a one-off webhook, or a language the SDK does not cover, they point you to the API trigger instead. A third option needs no code at all: webhook triggers let any system that can send an HTTP request start an agent, and the native app integrations cover most of the common SaaS sources before you write a line.

Keys, roles and regions come before the first request

Relevance AI separates two kinds of keys, and mixing them up is the first setup mistake to avoid. A Relevance API key authenticates your own code against the platform; anyone with the Editor role or above can generate one. On Enterprise plans, Members can also create personal keys, mainly to connect MCP clients such as Claude Desktop, Cursor or VS Code, and they manage only their own. Custom API keys for third-party services are a different store: encrypted, scoped to the project, and used inside tool steps through a secrets template variable, redacted when printed.

SDK keys deserve care. They start with sk-, grant full access to a project, and belong in server-side code only. They also never expire on their own, so a leaked key stays live until someone revokes it by hand in the dashboard ^[2]. Browsers get embed keys instead. Each one is generated at runtime, bound to exactly one public agent or workforce, and is the only safe way to authenticate from a page. Private agents cannot be reached this way. A front end that talks to three agents needs three embed keys.

Regions are the other fixed setting. API endpoints follow the form api-REGION.stack.tryrelevance.com/latest/, and the region id sits on the API keys page. Relevance AI runs three data regions: US (N. Virginia), EU (London) and AU (Sydney). The region is picked when the organization is created and cannot be changed later; moving needs a new organization through support. The SDK client must be set to the region where the project was created, and the API documentation itself is hosted separately for each region.

Triggering an agent over the REST API

1. Generate a Relevance API key and note the region id. The key is shown only once, though you can regenerate it.
2. Send a POST to your region's agents/trigger endpoint, with the key in the Authorization header and a body holding the message and the agent_id.
3. Give the agent a destination for its result, such as Google Sheets, a webhook or another integration.

Step three is the one teams skip. The call starts the work and returns without the agent's answer, so a caller that waits for one will wait forever. Plan the round trip up front: either the agent writes its output somewhere your system already reads, or you switch to the SDK and follow the task. Anything beyond triggering Agents and Tools is outside official support, even where an endpoint exists. API usage is rate-limited by subscription plan, and the trigger page prints no numbers for any plan.

Webhook triggers are the lighter route for event sources you do not control. Each takes a message template, an optional Thread ID mapping to keep related events in one conversation, and an optional Unique ID mapping. Map that ID. With it, a repeated event carrying the same ID is ignored, so a sender that retries cannot start the same work twice.

Building on the JavaScript/TypeScript SDK

The SDK is published on npm and JSR, has zero dependencies, ships full TypeScript definitions, and runs in Node.js, Deno, Bun, Cloudflare Workers and the browser. The quickstart needs three values: an API key from Integrations and API Keys, the project ID and the project region. Its central call, sendMessage, returns a Task immediately rather than waiting for the agent. That design suits the platform, because agent work can pause for approvals or queue behind other tasks.

A task is one conversation thread. Its SDK status is one of not-started, idle, paused, queued, running, action, completed, canceled or error. The action status matters most: it means a human must step in, because the platform state is pending-approval or escalated. Timed-out and unrecoverable runs map to error. Once you subscribe to a task, the SDK polls for new messages, opens a streaming connection where it can, and streams thinking and typing tokens with no extra configuration. Call unsubscribe when you are done, or the polling keeps running.

Listing works differently for agents and workforces. You can load an agent by ID, list a project's agents (20 per page by default) and list an agent's tasks (100 per page) with sorting, status filters and search. Workforce task listings use cursor pagination and support search only. Workforce tasks also accept no file attachments, while agent tasks do, and a workforce that hits its execution limit reports error. The platform routes messages between a workforce's agents, so your app never coordinates the handovers itself. The docs document no SDK beyond JavaScript and TypeScript; other languages go through the REST trigger.

Handing the build to a coding agent through MCP

The MCP server lives at mcp.relevanceai.com and works with Claude Desktop, Claude Web, ChatGPT, Cursor, VS Code, Windsurf, Codex, Zed and v0 ^[3]. Through it, a coding agent can create agents, tools and workforces, run them, troubleshoot them and review an agent's past conversations to find failures. For Claude Code the docs recommend the Relevance AI plugin over a manual connection, since it bundles the server with built-in skills. It needs Claude Code 1.0.33 or later and authenticates once through /mcp. Installation is two commands: claude plugin marketplace add RelevanceAI/cc-plugin, then claude plugin install relevance-ai@cc-plugin. Codex connects with codex mcp add and a browser login, and the agent-skills repository covers all 46 MCP tools.

Authentication is per project. Each login ties the session to one project, so two projects need two server entries, each authenticated on its own. Roles shape what a session can do. Admin, Editor and Member get full access by default and can opt into Run-Only at the consent screen; Viewer is forced into Run-Only, and Chat users get Chat mode. Run-Only removes write and destructive tools on the server, not just in the client. Since May 2026, Members in RBAC-enabled organizations can use MCP too, with requests running under their own auth.

Long runs need the async path. The synchronous relevance_trigger_agent tool times out after 120 seconds. Longer runs, and any agent with workforce nodes, should use the async trigger, which returns a conversation ID that the coding agent polls every 3 to 5 seconds until the run completes or fails. The traffic also runs the other way: your own agents can call outside MCP servers, with presets for Notion, Canva and Atlassian or any remote URL that supports Streamable HTTP. Local servers configured on your machine are not supported.

What API traffic costs and where it queues

Every door bills the same meters. Each Tool run counts as one Action, and a failed run still counts ^[4]; model and tool costs come out of Vendor Credits. Your own model keys cut Vendor Credit spend but not the subscription or Actions. Pro includes 2,500 Actions a month, so volume is worth sizing before you wire a busy backend to an agent.

Here is a simple case. A backend triggers an agent 100 times a day, and each run calls one Tool. Over a 30-day month that is 3,000 Actions, 500 more than Pro includes. Action top-ups come in packs of 1,000, so Pro at $29 a month billed monthly plus one $80 pack comes to $109 for that month and 3,500 Actions, by our arithmetic; unused top-up Actions roll over to the next billing cycle.

The threshold to watch: if your model spend fits Pro's 10,000 Vendor Credits a month, above 6,500 Actions a month on monthly billing, Team at $349 a month billed monthly costs less than Pro billed monthly plus top-ups. On annual billing the crossover comes earlier, at about 62,000 Actions a year (roughly 5,200 a month), by our arithmetic. Real runs that call several tools multiply the count.

Throughput has its own ceiling. Concurrency counts tasks running at once across the whole organization, and Relevance AI's docs give it per plan only as Standard, More or Custom. When capacity runs out, extra tasks queue rather than fail, which is another reason the SDK's queued status exists. A concurrency chart under Settings, Plan and Billing shows usage in real time. Before you commit traffic to one plan, the buyer's checklist maps which controls start on Team and which on Enterprise.

Choosing a first integration path on Relevance AI

Start with the job, not the tool. If an outside system only needs to kick off work and the result can land in a sheet, a CRM or a webhook, a webhook trigger or one REST call is enough, and Unique ID mapping keeps retries from doubling the work. If your app needs to show the agent's reply, approvals or streaming tokens, use the SDK with an sk- key on the server and embed keys in the browser. If your team already writes code with Claude Code or Codex, the free MCP server lets that agent build the agents, while Run-Only sessions keep everyone else read-and-run. Size Actions before launch either way.