MCP integrations

MCP integrations let your organisation connect external tools to Crafted AI. After installation, each MCP server appears in the plugin registry and can be used by the gateway and by WhatsApp app configurations.

MVP status

The MVP supports HTTP-based MCP servers with cached tool catalogs. Customer-hosted MCP servers are supported; Crafted AI-hosted custom plugins and a public marketplace are coming later.

Supported transport

Each MCP integration has:

Field	Meaning
endpoint	Public HTTPS URL for the MCP server.
transport	streamable-http by 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 an MCP server

In the control panel, open Plugins → Install MCP server.

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 and must be kebab-case. Examples: support-crm, billing-tools, warehouse-search.

Available now

Installed MCP servers appear under Plugins with their tool count, refresh status, and catalog metadata.

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 list tools on every page load.

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.

Tool invocation still calls the live MCP server. The cached catalog is for discovery and tool injection, not for executing tools.

Use MCP tools from the gateway

When the organisation has MCP plugins and a chat-completions request omits tools[], the gateway can inject the MCP tools into the model request. Tool names are prefixed with the plugin slug.

For example, an MCP tool named lookup_customer from a plugin with slug support-crm becomes:

support-crm__lookup_customer

The model sees the prefixed tool name and input schema. Crafted AI maps the tool call back to the correct MCP server, invokes it, appends the result, and continues the model loop.

Use MCP tools from WhatsApp

Open WhatsApp and select the MCP plugins that the inbound assistant may use. The WhatsApp reply worker passes only those IDs to the gateway.

This lets you install broad organisation tools while exposing a smaller set to the public WhatsApp surface.

Coming soon

Fine-grained per-tool allowlists in the control panel are planned after the MVP. For now, expose a narrowly scoped MCP server when a WhatsApp assistant should only use a subset of tools.

Control-panel API shape

Create

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
}

Refresh

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

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "kind": "mcp",
  "slug": "support-crm",
  "displayName": "Support CRM",
  "description": "Lookup customer records and support tickets.",
  "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,
  "lastRefreshAttemptedAt": "2026-05-08T12:00:00.000Z",
  "createdAt": "2026-05-08T12:00:00.000Z",
  "updatedAt": "2026-05-08T12:00:00.000Z"
}

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 check that the MCP server exposes tools.
Tool timeout	Increase timeoutMs up to 60000 or reduce the MCP server’s latency.
Plugin not visible in WhatsApp	Confirm the plugin is selected in the WhatsApp app config.

Security guidance

• Prefer HTTPS endpoints.
• Scope MCP server credentials to only the operations the model needs.
• Avoid exposing destructive tools until you have 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, or Credentials for key and secret handling.