# Relevance AI MCP

> Relevance AI MCP Server connects your preferred AI client (Claude, Cursor, etc.) directly to a professional agent orchestration platform. This server gives you tools to list, trigger, and monitor entire multi-agent teams—from initiating complex 'Studios' to checking task results in real time. You get full control over autonomous AI workflows without leaving your chat window.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** multi-agent-systems, autonomous-agents, workflow-automation, task-orchestration, ai-infrastructure, llm-ops

## Description

You connect your AI client straight into a professional agent orchestration platform, giving you full control over multi-agent teams without ever leaving your chat window. This server lets you manage complex autonomous workflows through simple calls to specific tools.

**Getting Started and Discovery:**
You need to know what’s running before you kick off anything big. You can pull a roster of every active AI agent persona available in the workspace by calling `list_agents`. If you want to see exactly what capabilities an agent has, use `get_agent_details` to retrieve its full metadata and configuration. When it comes to custom workflows, you don't have to guess; run `list_tools` to enumerate every 'Studio' or specialized tool the agents can execute.

**Executing Workflows and Tasks:**
To get work done, you start tasks. You trigger an entire multi-step process by calling `trigger_agent`, giving a specific agent persona its initial inputs for processing. For highly specialized needs, you bypass the full workflow and run a custom tool instantly using `trigger_tool` with required parameters. These tools let you execute complex, pre-built workflows immediately.

**Checking Status and History:**
Once something starts running in the background, you need to track it down. Use `get_task_status` to get a real-time update on any task—whether it’s still pending or if it's done for good—and grab its final output data. To see a summary of everything that’s been started or finished by your agents, run `list_agent_tasks`. For a deep dive into the platform's history, you can retrieve detailed historical records for all past agent runs using `list_executions`. If a task is complete and you need to clear up space, `delete_task` permanently removes specific, completed task records from the system.

**Managing Knowledge and Data:**
Your agents need data that isn't in their training set. To ground them in your company’s private knowledge, you can list available knowledge bases using `list_knowledge_items`. You also get specific details from a designated knowledge base by calling `get_knowledge`, allowing the AI to pull precise facts into its process.

This setup gives you an operations control panel built right into your chat. You manage everything—from initiating complex, multi-step agent teams to checking task results and deleting old records—all without jumping between separate dashboards or refreshing pages.

## Tools

### get_knowledge
Gets specific details from a designated knowledge base used by the agents.

### list_executions
Retrieves detailed historical records for all past agent executions across the platform.

### delete_task
Permanently removes a specific, completed task record from the system.

### get_agent_details
Retrieves metadata about an agent, showing its general configuration and capabilities.

### get_task_status
Checks the current status and final results of any background task run by an agent.

### list_agents
Provides a list of all active AI agent personas available in the workspace.

### list_knowledge_items
Lists specific, indexed items available within a knowledge base.

### list_agent_tasks
Lists a summary of recent tasks completed or started by your autonomous agents.

### list_tools
Enumerates all custom 'Studios' or tools that can be run by the agents.

### trigger_agent
Starts a new, defined task using a specified agent persona and its initial input data.

### trigger_tool
Executes a specific custom tool (Studio) immediately with required parameters.

## Prompt Examples

**Prompt:** 
```
List all my available autonomous agents.
```

**Response:** 
```
I've retrieved your agents. You have 3 active personas: 'Market Researcher', 'Data Analyst', and 'Sales Lead'. Which one would you like to trigger?
```

**Prompt:** 
```
Show me all AI agents in my workspace with their execution statistics from the last 7 days.
```

**Response:** 
```
6 AI agents in your workspace. "Customer Support Agent" ran 1,234 tasks (98.2% success rate, avg 3.4s response time). "Lead Qualifier" processed 567 leads (87% accuracy on scoring). "Content Writer" generated 89 articles (avg quality score: 8.4/10). "Data Analyst" executed 234 queries. "Email Responder" handled 456 emails. "Research Agent" completed 78 deep research tasks. Total executions: 2,658. Total tokens used: 4.2M. Cost: $84.60.
```

**Prompt:** 
```
Trigger the Lead Qualifier agent to analyze and score a batch of 50 new inbound leads.
```

**Response:** 
```
Lead Qualifier agent triggered for batch processing. 50 leads submitted for analysis. Processing status: 34 completed, 16 in queue. Results so far: 8 scored as Hot (80-100), 14 as Warm (50-79), 12 as Cold (below 50). Top lead: Sarah Chen from Meridian Corp (score: 96, enterprise budget confirmed, immediate need). 3 leads flagged for manual review due to incomplete data. Estimated completion: 2 minutes. Results will be synced to your CRM automatically.
```

## Capabilities

### List Agents
You retrieve a roster of every active agent persona running in your workspace, knowing exactly what capabilities you have available.

### Trigger Agent Workflows
You start an entire multi-step task by calling a specific agent and providing it with initial inputs for processing.

### Run Custom Tools (Studios)
You execute specialized, pre-built workflows—the 'Studios'—by passing complex parameters directly through the chat interface.

### Check Task Status and Results
You get a real-time status update on any background task, whether it’s pending or finished, along with its final output data.

### Manage Agent Knowledge
You list available knowledge bases or search through specific items within an agent's dedicated dataset using natural language queries.

## Use Cases

### Auditing a Failed Campaign
A campaign failed because an agent used bad data. Instead of digging through logs, you use `list_executions` to get the full history of runs and then use `get_task_status` on the specific job ID to see exactly which step failed and why.

### Onboarding a New Agent Persona
You need to know what capabilities your team has. You start by calling `list_agents` to get all available personas, then use `get_agent_details` on the new one to confirm its specific parameters and inputs.

### Running a Batch Analysis
You have 50 leads that need scoring. You don't want a conversation; you just want results. You call `trigger_tool` directly, passing the batch data payload to the 'Lead Qualifier Studio,' and get immediate status updates.

### Cleaning Up Old Data
A task ran years ago that generated junk data. Before running a new job, you use `delete_task` with the old ID to permanently remove the record, keeping your history clean and accurate.

## Benefits

- Task Lifecycle Visibility: Instead of guessing, use `get_task_status` to check if a background job is still running or if the final results are ready. You get immediate answers without refreshing dashboards.
- Full Workforce Listing: The `list_agents` tool shows you every single agent persona available right now. This lets you know exactly which specialized worker you need for the job.
- Complex Workflows on Demand: Use `trigger_tool` to run a specific 'Studio' with complex parameters, bypassing the standard conversational flow when precision is needed.
- Historical Audit Trail: The `list_executions` tool gives you access to every past agent interaction. This is critical for debugging or reviewing billing reports later.
- Knowledge Control: You don't just assume agents know things; use `get_knowledge` and `list_knowledge_items` to verify the exact data source they are reading from.

## How It Works

The bottom line is: Your AI client becomes a central, single point of control for managing all your complex, autonomous AI teams.

1. Subscribe to the server, then provide your Relevance AI Region Code and API Key credentials.
2. Your AI client sends a request (e.g., 'Show me all agents') which triggers one of the 11 listed tools on this MCP Server.
3. The tool executes the action—like listing tasks or triggering an agent—and sends the structured result back to your chat window.

## Frequently Asked Questions

**How do I check the status of a running task using get_task_status?**
You call `get_task_status` and provide the specific unique Task ID. The result tells you if it's PENDING, IN_PROGRESS, or COMPLETE, giving you real-time visibility on background jobs.

**Which tool do I use to run a custom studio?**
You must use `trigger_tool`. This function requires you to specify the exact Studio name and all necessary parameters defined when the tool was built. It's more precise than just talking to an agent.

**What is list_agents for?**
`list_agents` gives you a comprehensive roster of every autonomous AI persona active in your account. This helps you quickly identify which specialized worker can handle the task at hand.

**How do I use the `delete_task` function if I need to remove old or sensitive task logs?**
The `delete_task` tool permanently removes a specific task record. You must provide the exact Task ID, as this action cannot be undone and is used for cleanup or compliance purposes.

**What information does `get_knowledge` retrieve about an agent's knowledge base?**
It fetches detailed metadata for a specified knowledge base. You can see the scope, data sources, and contents of the knowledge item without needing to search through every document manually.

**If I need to audit performance, how do I use `list_executions`?**
The `list_executions` tool generates a comprehensive log of all agent activity. This history includes timestamps, inputs used, and final outcomes, allowing you to track system performance over time.

**Before starting an agent, how do I check its configuration using `get_agent_details`?**
This tool provides the agent's full metadata. You confirm the agent's intended role, required permissions, and current operational status without triggering any tasks or incurring costs.

**What happens if I use `trigger_tool` but provide incorrect parameters?**
The system immediately returns an error code along with a specific message. This feedback identifies exactly which parameter failed validation, letting you correct the input structure right away.

**Can my AI automatically trigger another autonomous agent in Relevance AI?**
Yes! Use the `trigger_agent` tool. Provide the `agent_id` and the user message/goal, and your agent will initiate the autonomous workflow in your Relevance account instantly.

**How do I find my Region Code and API Key?**
The Region Code is in your dashboard URL (e.g., `bcbe5a`). For the API Key, log in to Relevance AI, navigate to **Settings** > **API Keys**, and generate a new secret key.