Plugins

Plugins and MCPs are how a Bot gets new tools. The Bot decides which plugins it has access to via its allowedPluginIds allowlist. The gateway tool-call orchestrator handles invocation at request time.

Read Concepts and Bots first.

The unified plugin port

Crafted AI exposes two kinds of plugin behind one abstraction:

• First-party plugins — shipped by Crafted AI and run in-process. The WhatsApp plugin is the current first-party plugin.
• MCP-backed plugins — customer-installed MCP servers that expose tools over HTTP transports.

Both kinds register in the same plugin registry and appear identically to the gateway orchestrator. There is no special-casing in the tool loop based on plugin kind. See MCP integrations for installation details.

Allowlist and rate limits

A Bot’s allowedPluginIds is the allowlist that scopes which plugins the gateway may inject for that bot’s requests. Plugins installed in the org but absent from the allowlist are invisible to any request resolved through that bot.

Within each plugin, rate limits apply per tool. Per-tool rate limits are the current sandbox boundary — they prevent runaway tool invocation without full container isolation.

Container sandbox is deferred

Full MCP sandboxing with container isolation and egress allowlists is planned for Phase 2.5. Do not connect untrusted MCP servers unless you are comfortable with their network access and data handling.

Where plugins show up

After a bot resolves, plugins participate in two paths:

1. Gateway API path — applications call POST /v1/chat/completions. The gateway injects the bot’s allowed plugin tools into the request (unless the caller sends tools[] directly, which bypasses plugin orchestration).
2. WhatsApp inbound path — the reply worker calls the same gateway runtime using the bot bound to the WhatsApp number. Only the bot’s allowed plugins are eligible.

First-party plugins

WhatsApp plugin

The WhatsApp first-party plugin exposes Twilio-backed sending tools:

Tool	Purpose
whatsapp__send_message	Send a WhatsApp text message, optionally with media URLs.
whatsapp__send_template	Send an approved Twilio Content API template.

Tool names are prefixed as <plugin-slug>__<tool-name> when injected into the gateway request. The prefix keeps tools from different plugins from colliding.

Tool injection rules

The gateway decides whether to run plugin orchestration per request.

Request state	Behaviour
No bot resolved	Request goes directly to the upstream model provider.
Bot resolved, request includes tools[]	Plugin orchestration does not run; caller-supplied tools pass through.
Bot resolved, no tools[], bot allowlist is empty	Request goes directly to the upstream provider.
Bot resolved, no tools[], bot has allowed plugins	Gateway injects allowed plugin tools and runs the tool loop.

Client-owned tools

If your application needs to own tool execution itself, send tools[] in the chat-completions request. Crafted AI will not run plugin orchestration for that request.

Gateway loop

When plugin orchestration is active:

1. Crafted AI lists available tools for the bot’s allowed plugins.
2. Tool descriptors are converted into OpenAI-compatible function tools.
3. Tool names are prefixed with the plugin slug.
4. The gateway sends the request to the selected model.
5. If the model returns tool calls, Crafted AI invokes the tools server-side.
6. Tool results are appended to the conversation.
7. The gateway repeats until the model returns a final answer or the loop cap is reached.

Tool calls are tracked as usage events so teams can audit plugin activity by organisation, plugin, model, and request.

Control-panel API shape

List plugins

GET /organizations/{organizationId}/plugins
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "kind": "mcp",
      "slug": "support-crm",
      "displayName": "Support CRM",
      "description": "Lookup customer records.",
      "toolCount": 3
    },
    {
      "id": "first_party:whatsapp",
      "kind": "first_party",
      "slug": "whatsapp",
      "displayName": "WhatsApp",
      "description": "Send WhatsApp messages and templates via Twilio.",
      "toolCount": 2
    }
  ]
}

Use in gateway

curl "$CRAFTED_AI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CRAFTED_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Check whether customer 123 has an open ticket." }
    ]
  }'

Next: install an MCP integration, configure a Bot to attach plugins to it, or read WhatsApp to understand how plugin selection works for inbound threads.