> ## Documentation Index
> Fetch the complete documentation index at: https://wabis.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# External Capabilities

> Connect the agent to your own APIs or MCP tools, beyond the platform's built-in capabilities.

## What is this?

**External Capabilities** let the agent call systems outside the platform — your own REST API, or a tool exposed by an MCP server — the same way [Capabilities](https://wabis.mintlify.site/workspace/ai-agents/tabs/capabilities.md) let it act on contacts and automations. Use this once your first agent is working and you need it to reach something the built-in capabilities don't cover.

> [!NOTE]
>
> Adding an external capability requires the `automations:edit` permission. The tab only appears after the agent has been saved for the first time — save on [General](https://wabis.mintlify.site/workspace/ai-agents/tabs/general.md) first.

## What can I do here?

Click **Add External Capability** and choose a **Type**:

| Type | Use it when |
| - | - |
| **HTTP Request / Webhook** | You want the agent to call your own REST API — check an order in your own system, look something up, submit data to a form |
| **MCP Tool** | You have an MCP server exposing one or more tools and you want the agent to call them directly |

After saving, each capability appears as a card. A card in the **Needs login** state is saved but switched off — the agent won't use it until you edit it and add valid credentials.

## How to use it

### Add an HTTP Request capability

**1. Open the dialog**

Click **Add External Capability**, choose **HTTP Request / Webhook**, and fill in:

| Field | What to enter |
| - | - |
| **Display Name** | A short, clear name — e.g. *Check Order Status* |
| **When should the AI use this tool?** | A specific, one-sentence instruction — e.g. *Use this when the customer asks for the status of their order by number* |
| **Method** | GET, POST, PUT, PATCH, or DELETE |
| **URL** | The endpoint to call. Supports `{{variable}}` placeholders. |
| **Request Body** | JSON body (POST/PUT/PATCH). Supports `{{variable}}` placeholders. |
| **Extra headers** | Any headers your API needs (e.g. `Content-Type`, `X-Api-Version`). |
| **Authentication** | See [Authentication](#authentication) below. |
| **Inputs** | Define each `{{variable}}` used in the URL or body as a named input with a description. The AI collects these from the customer before calling the tool. |

**2. Test it (optional)**

Click **Test** to send a real request from the dialog before saving. Fill in sample input values and read the response.

**3. Save**

Click **Save**. The capability is immediately available to this agent.

### Add an MCP Tool capability

**1. Open the dialog**

Click **Add External Capability**, choose **MCP Tool**, and enter:

* **MCP Server URL** — the `https://` address of your MCP server.
* **Authentication** — if the server requires it, see [Authentication](#authentication) below.
* **Extra headers** — any custom headers the server needs.

**2. Fetch tools**

Click **Fetch tools from server**. The dialog connects to the server and lists all the tools it exposes. Tick the ones you want this agent to use — a separate capability is created for each one, with its inputs and description pre-filled from the server's own schema.

If the server returns `401` or `403`, the capability is saved in the **Needs login** state — it is off until you edit it, add valid credentials, and fetch again.

If your server isn't reachable, or you already know the tool name, you can type it manually under **Type a tool name**.

**3. Set 'When should the AI use this tool?' (single tool)**

When you select exactly one tool, a **When should the AI use this tool?** field appears. Write a specific instruction — e.g. *Use this when the customer asks to reschedule a booking*. Click the **sparkle icon** to have AI rewrite it based on the tool's name and inputs.

When multiple tools are selected, each tool uses its own description from the server automatically. You can edit them individually after they are created.

**4. Save**

Click **Save**. Each selected tool appears as its own capability card.

### Authentication

Both HTTP and MCP capabilities support the same authentication options:

| Auth type | When to use it |
| - | - |
| **None** | Your API or server is open, or you authenticate via a header instead |
| **Bearer Token** | Your API uses a static `Authorization: Bearer <token>` header — paste your token in the **Token** field |
| **OAuth 2.0 (Client Credentials)** | Your server issues short-lived access tokens. Enter your **Client ID**, **Client Secret**, and (for HTTP tools) a **Token URL**. For MCP tools the token endpoint is auto-discovered from the server. |

Credentials are stored encrypted and never shown in call records or to the customer.

### Write the "When should the AI use this tool?" field like you mean it

This one field is the entire decision surface. Vague descriptions mean the agent won't reach for the tool reliably even when it should; a specific instruction gets matched correctly against real customer messages. Use the **sparkle icon** to let AI rewrite your draft.

> [!TIP]
>
> Bad: *"Order lookup tool"* — Good: *"Use this when the customer asks for the status of a specific order by order number"*

### Fix a capability stuck in "Needs login"

If a capability card shows **Needs login**:

1. Click **Edit** on the card.
2. Enter the correct token or OAuth credentials.
3. Click **Fetch tools from server** (MCP) or **Test** (HTTP) to verify the connection.
4. Click **Save**. The card changes to show the capability is connected and on.

### Edit or remove a capability

Click **Edit** on a card to change any field. Click **Remove** to delete it — the agent stops using it immediately and this cannot be undone.

## Troubleshooting / Technical Notes

* **I don't have permission to add one.** You need `automations:edit` — check with your workspace admin.
* **The tab is empty right after creating the agent.** Save the agent on [General](https://wabis.mintlify.site/workspace/ai-agents/tabs/general.md) first — External Capabilities only unlocks afterward.
* **The agent never calls it.** Almost always the "When should the AI use this tool?" description — make it specific to a real customer request, not a generic label. Also check the capability is toggled on (visible in the card, not showing Needs login).
* **Fetch tools returns "No tools found".** The server is reachable but lists no tools for your key, or the server does not implement the MCP tools/list endpoint. Check your server logs.
* **Fetch tools fails with 401/403.** Your credentials are wrong or missing — the capability is saved as Needs login. Edit it and enter valid credentials.
* **Test says "Could not reach your server".** The URL must start with `https://` and be reachable from the internet (not `localhost`).
* **A `{{variable}}` in the URL or body is not working.** Make sure a matching Input is defined — if the variable isn't in the Inputs list, it won't be filled in and every call will fail.

## Related docs

* [Capabilities](https://wabis.mintlify.site/workspace/ai-agents/tabs/capabilities.md)
* [Skills](https://wabis.mintlify.site/workspace/ai-agents/tabs/skills.md)
* [Integrations](https://wabis.mintlify.site/workspace/integrations/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.