MCP Server

The Runbear MCP server is a hosted Model Context Protocol endpoint that lets an AI client — Claude Code, Claude Desktop, Cursor, and other MCP-compatible tools — read and manage the agents in your Runbear organization. Instead of clicking through the dashboard, you can describe what you want in natural language ("update the Support agent's instructions", "schedule the Standup agent for 9am") and your client makes the change through the MCP server.

This is the opposite direction from Custom MCP: there, Runbear is the client that connects out to your tools. Here, Runbear is the server that your AI client connects into to manage your agents.

What you can do#

From any connected MCP client you can:

• Manage agents — list agents, read their full configuration, create agents, and update an agent's name, model, and instructions.
• Edit instructions and contexts — add, update, or remove the named context blocks that make up an agent's behavior.
• Connect apps and tools — search the Runbear app catalog (Notion, Slack, Stripe, Linear, and more), attach integrations to an agent, and authorize them.
• Set up triggers and schedules — create app-event and HTTP webhook triggers or recurring and one-time scheduled jobs, and run scheduled jobs on demand.
• Deploy to Slack — install an agent into a Slack workspace, join channels, and go live.
• Inspect runs — pull recent execution traces to debug behavior and improve your agents.
• Ship files to a Claude Agent SDK agent — upload a project or a large workspace, as the Agent Skills do.

Connect#

The server URL is:

https://api.runbear.io/mcp

When you add the server, your client opens a Runbear sign-in window so you can authorize access (see Authentication). After you approve, the client stores the token and you can start issuing commands.

Claude Code#

claude mcp add --transport http runbear https://api.runbear.io/mcp

Run any Runbear command afterward and Claude Code will prompt you to sign in the first time.

Claude Desktop / claude.ai#

Open Settings → Connectors → Add custom connector, paste https://api.runbear.io/mcp, click Connect, and complete the Runbear sign-in.

Cursor, VS Code, Windsurf, Zed, and other clients#

Clients with native remote-MCP support can add the URL directly. For clients that connect through mcp-remote, use:

{
  "mcpServers": {
    "runbear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.runbear.io/mcp"]
    }
  }
}

Transport#

The server speaks the MCP Streamable HTTP transport: POST, GET, and DELETE on https://api.runbear.io/mcp. It is stateless, so it keeps no session between requests, and it does not offer the older HTTP+SSE transport. A client that supports only that older transport can connect through mcp-remote, as shown above.

Requests from a web page on another origin are refused with 403 and {"error": "invalid_origin"}. Desktop and command-line clients send no browser origin and are unaffected.

Authentication and permissions#

The Runbear MCP server is protected by OAuth 2.0. Authorization is handled by Runbear's identity provider, which your MCP client discovers automatically — you never paste an API key or token by hand. The server publishes its OAuth protected-resource metadata at https://api.runbear.io/.well-known/oauth-protected-resource/mcp, and every 401 points to it in the resource_metadata parameter of its WWW-Authenticate header.

Every connection is:

• Tied to your user account — the server acts as you, with your permissions.
• Scoped to your organization — you can only see and change agents in the organization you signed in to.

Removing the server from your client, or signing out there, deletes the client's copy of the token. It doesn't revoke the token on Runbear's side.

Access is governed by least-privilege scopes:

Scopes are checked per tool: a call without the scope it needs returns a tool error rather than failing the connection.

Connection errors#

These are HTTP responses to the request itself, before any tool runs:

Available tools#

A client you connect yourself gets 39 tools, grouped below by what they manage. Most agent-scoped tools take an agentId; use list_agents to find it. Each tool needs the scope in its row.

Agents#

Instructions and contexts#

Apps and integrations#

Triggers and schedules#

Slack#

Traces#

Both trace tools also require the Admin or Owner role and read access to the agent. They read an agent that uses HIPAA data handling from its separate protected tracing path.

Claude Agent SDK agents#

These tools work only on Claude Agent SDK agents; on any other agent they return {"status": "blocked", "reasons": ["agent_must_be_claude_agent_sdk"]}. They take the agent's id or its dashboard URL, and you need permission to edit the agent. Agent Skills is the ready-made way to use them.

Authorizing an integration#

Registering an integration and authorizing it are separate steps. The usual flow is search_integration_catalog → add_integration → authorize_integration → get_integration_authorization. An integration can't be used while add_integration or get_integration_authorization says authorization is still required.

authorize_integration returns one of these statuses:

Never paste an API key, bearer token, or MCP server URL into the chat to set up an integration. When an app needs a secret, or you want to connect your own MCP server, set it up in the dashboard at https://app.runbear.io/agents/<agentId>/integrations, where credentials are stored in the vault and masked.

Setting up triggers#

App-event triggers#

An app-event trigger is created in five steps:

1. list_supported_trigger_types with a query such as gmail, to find the component key.
2. describe_pipedream_trigger_component with that key. Repeat it, passing back the previous dynamicPropsId and the values chosen so far, until the component has no required setting left.
3. find_pipedream_account_id for the app. If it returns null, call generate_pipedream_connect_token, open the link, connect the account, and look it up again.
4. create_external_trigger with the component key, its settings, the connected account, and optionally a triggerPrompt and notificationConfig.
5. get_trigger to read the trigger back and confirm how it's configured.

If the trigger's prompt uses another app (for example "file a Linear ticket"), register and authorize that app on the agent first, as described in Authorizing an integration.

HTTP webhook triggers use the same flow with the HTTP / Webhook component. Until a pending fix ships, neither create_external_trigger nor get_trigger returns the public URL to send requests to: open the trigger's page in the dashboard and copy its Webhook URL. Anyone who sends a request to that URL runs the agent, so treat it as a secret. See Triggers for what the agent receives.

Rules#

• Schedules. A periodic job takes a 5-field cron expression and an IANA timezone such as America/Los_Angeles, and shouldn't run more often than once an hour. A once job takes executeAt, a Unix time in milliseconds, which should be in the future. Until a pending fix ships, the MCP server doesn't enforce either rule: a more frequent cron is accepted, and a past executeAt runs the job immediately.
• Delays. To make an event trigger wait before running, start its triggerPrompt with @delay(10m) or @delay(2h): minutes or hours, at most 24 hours. The agent never sees the directive. Delays apply to event triggers only.
• Where the output goes. An event trigger delivers each run's result to the destinations in its notificationConfig: Slack (a DM or a channel), Microsoft Teams (a chat or a channel), or email, plus failed runs when notifyOnErrors is true. A scheduled job has exactly one destination: a Slack DM or channel (slackAppInstallationId plus target), or a Microsoft Teams chat or channel (teamsTarget, which posts a new message rather than a threaded reply). The two can't be combined. notify defaults to true; with notify: false and no destination, which is required when you give neither, the job runs silently: its tool calls still happen, but the reply isn't posted anywhere.
• Limits. An organization can have up to 50 event triggers by default, and triggered runs share a daily budget. See Triggers → Limits.
• Run now. run_trigger_now works on scheduled jobs. On event triggers it works only for legacy schedule-based triggers, which can no longer be created.
• Scheduling from chat. create_scheduled_job is refused when an admin has turned off Scheduling from chat under Settings → Agents. It is on by default. Until a pending fix ships, the refusal message still names the setting's old label, "Allow bots to create scheduled triggers".
• Filters. filterPrompt on update_trigger sets the plain-language condition that decides which events run the agent. It is in limited availability; see Triggers → Filtering events.

Prompts#

The server offers one MCP prompt, setup_runbear_trigger. It takes a request argument that describes the workflow in plain language ("when a Zoom meeting ends, summarize it to #team-notes") and walks your client through authorizing every app the workflow needs, discovering the right trigger component, creating the trigger, and reading it back.

The server exposes no MCP resources.

Built-in tools on an agent#

Every new agent created in the dashboard or with create_agent gets Runbear's own MCP server attached as one of its tools, bound to that agent. Through it the agent can edit its own instructions, contexts, integrations, and triggers, and read its own traces — for example, when a user asks it in Slack to "also check Linear from now on". On Claude Agent SDK agents these tools appear to the model as mcp__runbear__<tool>, which is the name hooks match on.

A session bound to one agent differs from a client you connect yourself:

• Every tool acts on that agent only, and none takes an agentId.
• list_agents, create_agent, get_personal_agent, and the Slack tools aren't available, so the user has to supply Slack ids for a destination.
• The Claude Agent SDK tools are available only when the agent is itself a Claude Agent SDK agent.
• A trigger or context that belongs to another agent is refused with host_agent_ownership_required.

Admins turn this off for new agents with Settings → Agents → Built-in tools. Existing agents keep what they have. Agents created with the REST API's POST /v1/agents don't get these tools.

Tool errors#

A tool that refuses a call returns a JSON body that says why, usually as an MCP tool result with isError: true, so your client can show the reason and carry on:

Some tools report a refusal as a normal result with a status instead:

• deploy_to_slack and get_slack_install_link return status: "unsupported_for_personal_agent" for a personal agent, which can't be deployed to Slack.
• The Claude Agent SDK tools return status: "blocked" with reasons, such as agent_must_be_claude_agent_sdk or agent_modify_permission_required.

Example prompts#

List my Runbear agents and show the model each one uses.
Update the Support agent's instructions to always greet the user by name.
Add a context block to the Sales agent describing our refund policy.
Search the app catalog for Linear and attach it to the Triage agent.
Schedule the Standup agent to run every weekday at 9am in #team-standup.
Deploy the Onboarding agent to our Slack workspace.
Show me the last 10 runs of the Billing agent and any errors.

Security#

• The server acts as you. It uses your account's permissions, only within your organization. Removing the server from your client doesn't revoke its token on Runbear's side, so treat a machine with a connected client like any signed-in device.
• Writes are explicit. Your client asks before each change, and operations that deploy or modify agents require the corresponding scope.
• Never paste credentials into chat. When an integration needs a secret (API keys, bearer tokens, custom MCP headers), set it up in the Runbear dashboard at https://app.runbear.io/agents/<agentId>/tools, where credentials are stored in the vault and masked. Conversation transcripts are retained by your client and LLM provider, so secrets pasted into chat would be exposed in scrollback and logs.

Limitations#

The MCP server covers the core agent-management workflow. These still need the dashboard:

• Knowledge-base sync (Notion, Confluence, Google Drive, SharePoint, websites).
• Advanced model settings such as temperature, reasoning effort, and response format. Over MCP you can set only the model and max tokens.
• Custom Slack app setup. deploy_to_slack with mode: "custom" hands off to a dashboard page.
• Private Slack channels. The bot can join only public channels over MCP; invite it to private ones from Slack.
• Slack for personal agents. Personal agents can't be deployed to Slack.
• Trigger sources other than app events, HTTP webhooks, and scheduled jobs, such as inbox events.

We're closing these gaps — expect the tool set to grow.

Related#

• Custom MCP — connect your MCP servers and tools to an agent (Runbear as the client)
• Agent Skills — deploy a local Claude Code project to a Claude Agent SDK agent
• Triggers — how triggers and scheduled jobs behave
• Tool integrations API — attach tools to an agent over REST instead
• Getting started — create an agent and deploy it
• Model Context Protocol — the open standard behind MCP