MCP integrations

Customer-hosted MCP servers become tool sources for a Bot. The primary path is install via Marketplace, then attach the resulting plugin to a Bot’s allowlist. Direct manual installation is supported for custom or self-hosted MCP servers.

Read Concepts first.

Supported transport

Each MCP integration has:

Field	Meaning
`endpoint`	Public HTTPS URL for the MCP server.
`transport`	`streamable-http` (default) or `http-sse`.
`timeoutMs`	Optional request timeout, capped at 60 seconds.
`credentialId`	Optional reference to a stored credential used when calling the MCP server.

Install via Marketplace (recommended)

Open Marketplace → MCP Templates and install from the curated catalog. The install modal surfaces required credential fields and any ${VAR}-templated endpoint values. After installation, the MCP server is registered as an org plugin and its tool catalog is fetched automatically. Source: CRA-244

Templates that use ${VAR}-style base URL templating let you point the server at your own hosted instance — enter the value during install and it is substituted into the endpoint configuration.

See Marketplace for the full catalog and install steps.

Direct testing and manual install

For custom or self-hosted MCP servers, install manually from the control panel.

Open Plugins → Install MCP server and enter:

Display name — human-readable name for the plugin list.
Slug — stable kebab-case identifier, such as support-crm.
Endpoint URL — the MCP server URL.
Transport — leave as streamable-http unless your server requires HTTP SSE.
Credential — optional, for MCP servers that need auth headers.

Slugs are unique per organisation. Examples: support-crm, billing-tools, warehouse-search.

Per-MCP credential capture

When installing via the Marketplace, each template that requires auth surfaces its required credential fields inline. Credentials are stored encrypted, scoped to the integration, and used when the gateway calls the MCP server at tool invocation time. Source: CRA-244

For manually installed integrations, link a stored credential by selecting it from the Credential dropdown during install or update.

Refresh the tool catalog

Crafted AI caches the MCP server’s tool descriptors so the plugin list and gateway tool injection do not need to call the server on every request.

Refresh the catalog when:

You install a new MCP server.
You change the MCP server’s tools or input schemas.
The plugin list shows a refresh error.
You update the endpoint or transport.

The catalog is also refreshed automatically on install. Tool invocation still calls the live MCP server — the cache is for discovery and injection only.

Attach to a Bot

Installing an MCP integration creates an org-level plugin. To make it available to a bot, add the plugin ID to the bot’s allowedPluginIds list. Do this in the control panel under Bots → [bot name] → Plugins, or via the bot update API. The plugin will not be used by any request until it appears in at least one bot’s allowlist.

See Bots for bot configuration and Plugins for the gateway tool-injection rules.

Control-panel API shape

POST /organizations/{organizationId}/integrations
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>
Content-Type: application/json

{
  "kind": "mcp",
  "slug": "support-crm",
  "displayName": "Support CRM",
  "description": "Lookup customer records and support tickets.",
  "config": {
    "endpoint": "https://mcp.example.com",
    "transport": "streamable-http",
    "timeoutMs": 30000
  },
  "credentialId": null
}

POST /organizations/{organizationId}/integrations/{integrationId}/refresh
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "kind": "mcp",
  "slug": "support-crm",
  "displayName": "Support CRM",
  "config": {
    "endpoint": "https://mcp.example.com",
    "transport": "streamable-http"
  },
  "credentialId": null,
  "toolCatalog": [
    {
      "name": "lookup_customer",
      "description": "Lookup customer profile by ID.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"]
      }
    }
  ],
  "catalogRefreshedAt": "2026-05-08T12:00:00.000Z",
  "lastRefreshError": null
}

Errors and troubleshooting

Symptom	What to check
`integration_slug_conflict`	Another integration in the organisation already uses that slug.
`invalid_integration_config`	Endpoint, transport, or credential configuration is invalid.
Empty tool count	Refresh the catalog and confirm the MCP server exposes tools.
Tool timeout	Increase `timeoutMs` up to 60000 or reduce the MCP server’s latency.
Plugin not visible in a Bot	Confirm the plugin ID is in the bot’s `allowedPluginIds`.

Security guidance

Prefer HTTPS endpoints.
Scope MCP server credentials to only the operations the model needs.
Avoid exposing destructive tools without human confirmation in the tool itself.
Keep MCP tool names and descriptions explicit — the model uses them to decide when to call a tool.
Rotate credentials through the control panel when access changes.

Next: read Plugins for gateway orchestration rules, Bots to attach plugins to a bot, or Credentials for key and secret handling.