---
title: "Create agent tool integration"
method: POST
path: "/v1/agents/{id}/tool-integrations"
---

# Create agent tool integration

`POST /v1/agents/{id}/tool-integrations`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents/{id}/tool-integrations`
- Auth: HTTP bearer

Attach an MCP, Pipedream, or Custom MCP integration to an agent. For `managed-mcp` the transport config is derived server-side from the catalog manifest. `pipedream` and `custom-mcp` integrations are created app-scoped (organization-wide). Returns 400 when the agent's provider does not support tool integrations, 404 when the agent is not found, and 409 when an integration for the same app already exists on the agent.

## Path parameters

- `id` string, uuid, required: Agent ID

## Request body

- union: Create a tool integration on an agent. Discriminated on `type`. For `managed-mcp` the server derives the transport config from the catalog manifest. `pipedream` and `custom-mcp` integrations are created as app-scoped (organization-wide).
  - object
    - `type` 'managed-mcp', required
    - `app` string, required: Managed MCP catalog slug (e.g., "notion", "hubspot"). The transport config is derived server-side from the catalog manifest.
    - `secrets` object
      - `envMap` object, required: Environment variable name → value map for stdio Managed MCP servers. Stored in the vault. Rejected for remote (OAuth) apps.
    - `excludedTools` string[]: Tool names to exclude from the agent's toolbox.
  - object
    - `type` 'pipedream', required
    - `nameSlug` string, required: Pipedream app slug (e.g., "firecrawl", "aws").
    - `authType` 'keys' | 'oauth' | 'none', nullable, required: Authentication style required by the Pipedream app.
    - `excludedTools` string[]: Tool names to exclude from the agent's toolbox.
  - object
    - `type` 'custom-mcp', required
    - `app` string, required: Display label for the MCP server.
    - `url` string, uri, required: Remote MCP server URL.
    - `transportType` 'sse' | 'streamableHttp', required
    - `auth` union, required
      - object
        - `type` 'oauth', required
      - object
        - `type` 'none', required
      - object
        - `type` 'static', required
        - `headerKey` string, required
    - `httpHeaders` object: HTTP headers forwarded to the MCP server. Use `secret` for values that should be stored in the vault.
    - `excludedTools` string[]: Tool names to exclude from the agent's toolbox.

## Response `201`

Default Response

- union: A tool integration attached to an agent. Discriminated on `type`: `managed-mcp` (Runbear-managed MCP server), `pipedream` (Pipedream connector), or `custom-mcp` (caller-hosted MCP server).
  - object
    - `id` string, uuid, required: Tool integration ID.
    - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
    - `createdAt` string, required
    - `updatedAt` string, required
    - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
    - `type` 'managed-mcp', required
    - `app` string, required: Managed MCP catalog slug (e.g., "notion").
  - object
    - `id` string, uuid, required: Tool integration ID.
    - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
    - `createdAt` string, required
    - `updatedAt` string, required
    - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
    - `type` 'pipedream', required
    - `nameSlug` string, required: Pipedream app slug (e.g., "firecrawl", "aws").
    - `authType` 'keys' | 'oauth' | 'none', nullable, required: Authentication style required by the Pipedream app.
  - object
    - `id` string, uuid, required: Tool integration ID.
    - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
    - `createdAt` string, required
    - `updatedAt` string, required
    - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
    - `type` 'custom-mcp', required
    - `app` string, required: Display label for the MCP server.
    - `url` string, required: Remote MCP server URL.
    - `transportType` 'sse' | 'streamableHttp', required
    - `auth` union, required
      - object
        - `type` 'oauth', required
      - object
        - `type` 'none', required
      - object
        - `type` 'static', required
        - `headerKey` string, required
    - `httpHeaders` object: HTTP headers forwarded to the MCP server. Vault-backed values expose only `keyName`, never the secret value.

## Other responses

- `400`: Default Response
- `404`: Default Response
- `409`: Default Response

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)