Plugins

Plugins are the way Crafted AI gives models safe, organisation-scoped skills. The plugin runtime exposes two kinds of plugin behind one surface:

• First-party plugins - shipped by Crafted AI and run in-process, such as the WhatsApp plugin.
• MCP-backed plugins - customer-installed MCP servers that expose tools over HTTP transports.

The gateway can inject plugin tools into a chat-completions request, let the model choose a tool call, execute the selected tool, and continue the model loop until a final assistant response is produced.

MVP status

Plugin registry and tool orchestration are part of the MVP. The public marketplace, hosted customer-built plugins, and full container sandbox are coming later.

Where plugins show up

Plugins can be used in two MVP paths:

1. Gateway API path - applications call POST /v1/chat/completions. If the organisation has plugins and the request does not include user tools[], Crafted AI can inject organisation plugins into the request.
2. WhatsApp inbound path - the reply worker calls the gateway with the WhatsApp app’s selected enabledPluginIds, so only those plugins are visible to the assistant.

First-party plugins

First-party plugins are built and operated by Crafted AI. They have stable slugs, stable tool names, and do not require you to host an MCP server.

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.

Coming soon

The first-party WhatsApp plugin is intended for outbound tool calls from gateway workflows. The inbound WhatsApp reply flow uses the same gateway runtime but sends the final assistant reply through the WhatsApp adapter directly.

MCP-backed plugins

An MCP integration becomes a plugin after it is installed for an organisation. Crafted AI stores its endpoint, transport, optional credential reference, and cached tool catalog.

Read MCP integrations for installation details.

Tool injection rules

The gateway decides whether to run plugin orchestration per request.

Request state	Behaviour
No plugin runtime configured	Request goes directly to the upstream model provider.
Request includes user tools[]	Crafted AI does not execute plugins; tools are passed through to the provider/client flow.
Organisation has no plugins	Request goes directly to the upstream provider.
Organisation has plugins and request omits tools[]	Crafted AI may inject plugin tools and run the tool loop.
WhatsApp app supplies enabledPluginIds	Only those plugin IDs are considered for the WhatsApp reply.

Important

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 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.

Security model

• Plugins are organisation-scoped.
• Gateway keys identify the organisation for API calls.
• WhatsApp reply flows receive only the plugins selected in the WhatsApp app.
• MCP integration writes require owner access.
• Plugin errors are scrubbed before they are returned to the model or logged.
• MVP sandboxing is based on tool allowlists and per-tool rate limits.

Coming soon

Full MCP sandboxing with container isolation and egress allowlists is planned after the MVP. Do not connect untrusted MCP servers unless you are comfortable with their network behaviour and data access.

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 or configure WhatsApp to control which plugins an inbound assistant can use.