Tool integrations API

The Tool integrations API gives an agent its tools from your own code: the same managed MCP servers, app integrations, and Custom MCP servers you would otherwise add on the agent's Tools tab. Use it to provision agents from a script, keep several agents' tools in step, or connect an internal MCP server as part of a deployment.

What you need#

• An API key. Reading needs no particular capability; creating, changing, and deleting integrations needs the manageAgents capability.
• An Anthropic, OpenAI Responses, or Claude Agent SDK agent. Other agent types don't take tool integrations through the API: writes to them answer 400 with provider_does_not_support_tool_integrations. Claude Agent SDK agents also need API access to be enabled for your organization, or requests answer 400 with claude_agent_sdk_not_permitted.

Endpoints#

Every request and response field is in the OpenAPI reference.

Integration types#

The type field decides which other fields an integration has.

managed-mcp#

A managed MCP server from Runbear's catalog, such as Notion or HubSpot. Find its slug with GET /v1/tool-integrations/managed-mcps, which also lists each server's transport, whether it uses OAuth, and its tools.

{
  "type": "managed-mcp",
  "app": "notion"
}

Runbear fills in the server's connection details from the catalog. A catalog server that runs as a local process may need environment variables, such as an API key. Pass them in secrets.envMap; they're stored in your organization's vault. Remote (OAuth) catalog servers take no secrets, and sending them answers 400 with secrets_not_supported_for_remote_managed_mcp.

pipedream#

An app integration, identified by its app slug.

{
  "type": "pipedream",
  "nameSlug": "firecrawl",
  "authType": "keys"
}

authType is how the app authenticates: keys, oauth, or none.

custom-mcp#

Your own MCP server.

{
  "type": "custom-mcp",
  "app": "context-server",
  "url": "https://mcp.example.com/mcp",
  "transportType": "streamableHttp",
  "auth": { "type": "static", "headerKey": "Authorization" },
  "httpHeaders": {
    "Authorization": { "type": "secret", "value": "Bearer sk-..." },
    "X-Team": { "type": "plain_text", "value": "support" }
  }
}

A secret header is stored in your organization's vault and never returned. When you read the integration back, it appears as { "type": "vault", "keyName": "..." }.

Some names are reserved for Runbear's own integrations, and a custom-mcp with one of them answers 400 with tool_integration_identity_reserved. A few vendors' MCP servers can only be connected from the dashboard; pointing a custom-mcp at one answers 400 with tool_integration_preset_not_supported_via_public_api.

Fields every type has#

• excludedTools — tool names to hide from the agent, for a server that offers more tools than the agent should use.
• status — read-only. ready means the integration is authorized and its tools are usable; pending_auth means someone has to finish signing in first.

pipedream and custom-mcp integrations created through the API use one shared connection for everyone who talks to the agent, rather than asking each person to connect their own account. Per-user connections are set up in the dashboard.

Changing and removing an integration#

PATCH replaces the integration's settings with the body you send, which has the same shape as the one for POST. The type and the integration's identity (app for managed-mcp and custom-mcp, nameSlug for pipedream) can't change; a request that changes them answers 400 with tool_integration_identity_immutable. To switch to a different app or server, delete the integration and create a new one. A secret header you send replaces the stored value.

Integrations set up with a per-user connection, or with a vendor preset, can be edited only in the dashboard; PATCH answers 400 with tool_integration_not_editable_via_public_api.

DELETE detaches the integration and deletes the secrets it stored in the vault.

Completing OAuth#

An integration that uses OAuth starts as pending_auth. To finish it:

1. Call POST /v1/agents/{agentId}/tool-integrations/{integrationId}/auth-url.
2. Open the returned authUrl in a browser and approve access. Runbear completes the sign-in on its side.
3. Read the integration again. Its status is now ready.

authUrl is null when the integration is already authorized. An integration that has no browser sign-in (a pipedream app with authType none, a managed MCP server that runs as a local process, or a custom-mcp with auth none or static) answers 400 with auth_url_not_applicable.

Errors#

These endpoints answer with a route-specific body, { "error": "<cause>", "message": "..." }, rather than the standard envelope. Branch on error:

Integration suggestions#

When someone asks an agent to do something with an app it isn't connected to, the agent can answer with an "Integration Required" message that links to Runbear's setup page. For agents whose users never see Runbear, such as one behind your own product, you can turn those suggestions off for the whole organization. There is no dashboard control for this; it is set through the API only.

Suggestions are on (disabled: false) by default.

Related#

• Custom MCP — the same servers, set up from the dashboard
• Tool catalog — the managed servers and apps you can attach
• Managing agents via API — create and configure the agents these integrations attach to
• Hooks API — call a Custom MCP tool at fixed points in a conversation
• MCP server — attach integrations from an AI client instead