MCP Integration

What This Does

MCP (Model Context Protocol) lets your AI coding tools talk directly to your BrainRoad agent. Once connected, you can type things like:

• “Send a message to my agent asking it to summarize today’s emails”
• “Check what cron jobs my agent has scheduled”
• “Tell my agent to install the weather skill”

Your coding tool (Claude Code, Cursor, etc.) calls your BrainRoad agent behind the scenes and gives you the result. No switching tabs, no copy-pasting URLs.

Step-by-Step: Connect Claude Code to Your Agent

Time required: 2 minutes.

1. Get your credentials

Open your BrainRoad dashboard and go to the API page (left sidebar → API).

You need two things from the MCP Integration section:

• MCP Endpoint URL — looks like https://app.brainroad.com/gw/user_abc123/mcp
• Gateway Token — a long string starting with letters and numbers

Click the copy button next to each one. Keep them handy.

2. Add the config to Claude Code

Open a terminal and run:

claude mcp add brainroad-agent \
  --transport http \
  --url "https://app.brainroad.com/gw/YOUR_USER_ID/mcp" \
  --header "Authorization: Bearer YOUR_GATEWAY_TOKEN"

Replace YOUR_USER_ID and YOUR_GATEWAY_TOKEN with the values you copied.

Or, if you prefer to edit the config file directly, add this to ~/.claude/settings.json (or your project’s .mcp.json):

{
  "mcpServers": {
    "brainroad-agent": {
      "url": "https://app.brainroad.com/gw/YOUR_USER_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GATEWAY_TOKEN"
      }
    }
  }
}

Tip: Your dashboard’s API page has a ready-to-paste config snippet with your real credentials filled in. Just copy and paste it.

3. Try it

Open Claude Code and type:

Ask my BrainRoad agent what its current status is

Claude Code will call the status tool on your agent and show you the result. That is it — your agent is now a tool that Claude Code can use.

Step-by-Step: Connect Cursor

1. Get your credentials

Same as above — Dashboard → API → MCP Integration section.

2. Add to Cursor

Open Cursor Settings → MCP Servers → Add Server, then paste:

{
  "brainroad-agent": {
    "url": "https://app.brainroad.com/gw/YOUR_USER_ID/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_GATEWAY_TOKEN"
    }
  }
}

3. Try it

In Cursor’s chat, type: “Use my BrainRoad agent to list its scheduled cron jobs.”

What Can You Do With This?

Once connected, your coding tool can call any of your agent’s 90+ methods. Here are the most useful ones:

What you want to do	What to ask your coding tool
Talk to your agent	”Send my agent this message: [your message]“
Check agent status	”What’s my BrainRoad agent’s current status?”
See conversation history	”Show me my agent’s recent chat history”
Schedule a task	”Tell my agent to check my email every morning at 8am”
Install a skill	”Have my agent install the weather-forecast skill”
Check costs	”How much has my agent spent today?”
Manage channels	”What messaging channels is my agent connected to?”

You do not need to know the exact method names. Just describe what you want in plain English and your coding tool figures out the right call.

Verify It Works (curl)

If you want to test the connection manually before setting up your editor:

# Check if your agent's MCP endpoint is reachable
curl -s https://app.brainroad.com/gw/YOUR_USER_ID/mcp/health

# List all available tools
curl -s https://app.brainroad.com/gw/YOUR_USER_ID/mcp \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Send a message to your agent
curl -s https://app.brainroad.com/gw/YOUR_USER_ID/mcp \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"chat_send","arguments":{"message":"Hello from MCP!"}}}'

A successful tools/list response means your agent is connected and ready.

Authentication

MCP uses your Gateway Token — the same token that authenticates WebSocket connections to your agent. It is not the same as a BrainRoad API key (those are for the platform API, not your agent).

Find your token: Dashboard → API → Gateway Connection → Gateway Token.

How It Works Under the Hood

Your BrainRoad agent runs a small MCP bridge alongside the main agent process. When Claude Code or Cursor sends an MCP request:

1. The request hits your agent’s unique URL (/gw/your-user-id/mcp)
2. The bridge translates the HTTP request into an internal call to your agent
3. Your agent processes it and sends back the result
4. The bridge returns the response to your coding tool

Each request is independent — no long-lived connections to manage. If your agent restarts, MCP requests will work again as soon as the agent is back up (usually under 30 seconds).

Troubleshooting

“Connection refused” or timeout: Your agent might be stopped. Go to Dashboard and start it.

“401 Unauthorized”: Your gateway token is wrong or expired. Copy a fresh one from Dashboard → API.

Health check returns {"status":"connecting"}: Your agent is still booting. Wait 30 seconds and try again.

Claude Code does not see the tools: Restart Claude Code after adding the MCP config. It only reads the config on startup.