> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Connection

> Connect to Beam AI using the Model Context Protocol (MCP) for seamless AI assistant integration

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](https://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

<Steps>
  <Step title="Navigate to Beam Dashboard">
    Go to [app.beam.ai](https://app.beam.ai) and sign in to your account
  </Step>

  <Step title="Open Personal Settings">
    Click on your workspace icon in the top left corner and select **Personal settings**
  </Step>

  <Step title="Access API Keys Section">
    In the settings menu, navigate to the **API Keys** section
  </Step>

  <Step title="Create New API Key">
    Click **Create New API Key** and give it a descriptive name
  </Step>

  <Step title="Copy Your API Key">
    Copy the generated API key and store it securely - you'll need it for the connection setup
  </Step>
</Steps>

<Warning>
  Keep your API key secure! Never share it publicly or commit it to version control. Treat it like a password.
</Warning>

## Connecting to Beam AI via MCP

### Using Claude Code CLI

The easiest way to connect is using the Claude Code CLI:

```bash theme={null}
claude mcp add --transport http beam-server https://api.beamstudio.ai/mcp --header "x-api-key: YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with the API key you generated in the previous step.

<Tip>
  After running this command, restart your AI assistant (Claude Desktop, Cursor, etc.) to activate the connection.
</Tip>

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

```json theme={null}
{
  "mcpServers": {
    "beam-server": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "https://api.beamstudio.ai/mcp",
        "--transport",
        "streamablehttp",
        "-H",
        "x-api-key",
        "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 header format** - Should be `x-api-key: YOUR_API_KEY`

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Rotate API Keys Regularly" icon="key">
    Periodically generate new API keys and revoke old ones for enhanced security
  </Card>

  <Card title="Use Separate Keys" icon="users">
    Create different API keys for different environments (development, production)
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly check API key usage in your Beam Dashboard
  </Card>

  <Card title="Revoke Compromised Keys" icon="shield">
    Immediately revoke any API key you suspect has been compromised
  </Card>
</CardGroup>

## Need Help?

If you encounter any issues or have questions:

* 📧 Email: [support@beam.ai](mailto:support@beam.ai)
* 💬 Discord: [Join our community](https://discord.gg/beam-ai)
* 📚 Documentation: [docs.beam.ai](https://docs.beam.ai)

***

<Info>
  MCP connection enables powerful AI-to-AI integration, allowing your assistant to leverage Beam AI's full capabilities seamlessly.
</Info>