Skip to main content
Connect Beam AI to your AI assistant using the Model Context Protocol (MCP). This enables you to access all Beam AI capabilities directly from Claude Desktop, Cursor, or any MCP-compatible client.

​
What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and services. By connecting Beam AI via MCP, you can:
  • 📋 List and view your AI agents
  • 🚀 Create and execute agent tasks
  • 📊 Monitor task progress and get real-time updates
  • ✅ Approve or reject tasks requiring user consent
  • 📈 Access agent analytics and performance metrics
  • 📁 Download agent context files

​
Prerequisites

Before connecting, you’ll need:
  1. A Beam AI account - Sign up at app.beam.ai
  2. An API key - Generate one from your Beam Dashboard
  3. An MCP-compatible client - Such as Claude Desktop, Cursor, or another MCP client

​
Getting Your API Key

1

Navigate to Beam Dashboard

Go to app.beam.ai and sign in to your account
2

Open Personal Settings

Click on your workspace icon in the top left corner and select Personal settings
3

Access API Keys Section

In the settings menu, navigate to the API Keys section
4

Create New API Key

Click Create New API Key and give it a descriptive name
5

Copy Your API Key

Copy the generated API key and store it securely - you’ll need it for the connection setup
Keep your API key secure! Never share it publicly or commit it to version control. Treat it like a password.

​
Connecting to Beam AI via MCP

​
Using Claude Code CLI

The easiest way to connect is using the Claude Code CLI: 
claude mcp add --transport http beam-server https://api.beamstudio.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"
Replace YOUR_API_KEY with the API key you generated in the previous step.
After running this command, restart your AI assistant (Claude Desktop, Cursor, etc.) to activate the connection.

​
Manual Configuration (Claude Desktop)

If you prefer to configure manually, edit your Claude Desktop configuration file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Add the following configuration: 
{
  "mcpServers": {
    "beam-server": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "https://api.beamstudio.ai/mcp",
        "--transport",
        "streamablehttp",
        "-H",
        "Authorization",
        "Bearer YOUR_API_KEY"
      ]
    }
  }
}
Replace YOUR_API_KEY with your actual API key.

​
Verifying the Connection

After connecting, you can verify the connection is working by asking your AI assistant: 
Can you list my Beam AI agents?
If connected successfully, the assistant will retrieve your agents from Beam AI and display them.

​
Available MCP Tools

Once connected, your AI assistant will have access to the following Beam AI capabilities:

​
User Management

  • getCurrentUser - Get your user profile and workspace information

​
Agent Management

  • listAgents - List all your AI agents
  • downloadContextFile - Download agent context files

​
Agent Configuration

  • getAgentGraph - Get agent workflow configuration
  • testGraphNode - Test specific workflow nodes
  • getTaskNodesByTool - Find tasks using specific tools

​
Task Operations

  • createAgentTask - Create new agent tasks
  • listAgentTasks - List all agent tasks
  • getTaskDetails - Get detailed task information
  • getTaskUpdates - Stream real-time task updates

​
Task Execution Control

  • submitUserInput - Provide input for paused tasks
  • approveTaskExecution - Approve tasks requiring consent
  • rejectTaskExecution - Reject task execution
  • retryTaskExecution - Retry failed tasks

​
Analytics & Optimization

  • getAgentAnalytics - Get agent performance metrics
  • rateTaskOutput - Rate task execution quality
  • optimizeTool - Optimize tool configurations
  • getToolOptimizationStatus - Check optimization progress

​
Example Usage

Here are some example commands you can use with your AI assistant once connected:

​
Create an Agent Task

Create a task for my "Customer Support" agent to analyze the latest support tickets

​
Monitor Task Progress

Show me the status of my running agent tasks

​
Get Agent Analytics

What's the performance analytics for my Sales Outreach agent from the last 7 days?

​
Manage Workflows

Show me the workflow configuration for my Data Analysis agent

​
Troubleshooting

​
Connection Failed

If you’re unable to connect:
  1. Verify your API key is correct - Try generating a new one
  2. Check your internet connection - Ensure you can reach api.beamstudio.ai
  3. Restart your AI assistant - Close and reopen the application
  4. Check the configuration file - Ensure the JSON syntax is correct

​
Tools Not Appearing

If the Beam AI tools don’t appear in your assistant:
  1. Restart your AI assistant completely - Quit and relaunch
  2. Check the connection status - Ask “What MCP servers are connected?”
  3. Verify API key permissions - Ensure your API key hasn’t been revoked

​
API Key Issues

If you’re getting authentication errors:
  1. Generate a new API key - Old keys may have expired
  2. Check for extra spaces - Ensure no whitespace in your API key
  3. Verify the Bearer format - Should be Bearer YOUR_API_KEY with a space

​
Security Best Practices

Rotate API Keys Regularly

Periodically generate new API keys and revoke old ones for enhanced security

Use Separate Keys

Create different API keys for different environments (development, production)

Monitor Usage

Regularly check API key usage in your Beam Dashboard

Revoke Compromised Keys

Immediately revoke any API key you suspect has been compromised

​
Need Help?

If you encounter any issues or have questions:
MCP connection enables powerful AI-to-AI integration, allowing your assistant to leverage Beam AI’s full capabilities seamlessly.