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

# MCP Tools

> Connect an external MCP server to inject custom tools into your chatbot

Connect your own MCP server to Animam. Your server's tools are auto-discovered and available in chat conversations — the AI can call them just like built-in tools.

<Note>
  Requires **Builder plan or above**. Your MCP server must support [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
</Note>

## How it works

1. You configure your MCP server URL on the tenant
2. At chat time, Animam calls `tools/list` on your server to discover available tools
3. Tools are injected into the AI's context (prefixed `mcp_` to avoid collisions)
4. When the AI decides to use one, Animam calls `tools/call` on your server
5. The result is returned to the AI, which incorporates it in its response
6. Tool discovery is **cached for 5 minutes** per tenant

## GET /tenants/{slug}/mcp-tools

Read current MCP tools configuration.

**Required scope:** `settings:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/mcp-tools \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "mcpToolsUrl": "https://mcp.example.com/mcp",
  "mcpToolsMaxTools": 10,
  "hasApiKey": true
}
```

## PUT /tenants/{slug}/mcp-tools

Configure or update the external MCP server connection.

**Required scope:** `settings:write`

### Request

```bash theme={null}
curl -X PUT https://api.animam.ai/tenants/my-company/mcp-tools \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpToolsUrl": "https://mcp.example.com/mcp",
    "mcpToolsApiKey": "your-bearer-token",
    "mcpToolsMaxTools": 10
  }'
```

### Response

```json theme={null}
{
  "mcpToolsUrl": "https://mcp.example.com/mcp",
  "mcpToolsMaxTools": 10,
  "hasApiKey": true
}
```

## DELETE /tenants/{slug}/mcp-tools

Remove MCP tools configuration.

**Required scope:** `settings:write`

```bash theme={null}
curl -X DELETE https://api.animam.ai/tenants/my-company/mcp-tools \
  -H "Authorization: Bearer ak_your_token"
```

## Configuration fields

| Field              | Type   | Required | Description                                                                    |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------ |
| `mcpToolsUrl`      | string | Yes      | Your MCP server URL. Must be HTTPS.                                            |
| `mcpToolsApiKey`   | string | No       | Bearer token sent to your server. Encrypted at rest (AES-256-GCM).             |
| `mcpToolsMaxTools` | number | No       | Max tools to import (1-20, default: 10). Safety limit to prevent prompt bloat. |

## MCP server requirements

Your server must implement the [MCP specification](https://modelcontextprotocol.io/) with Streamable HTTP transport:

* **`POST /mcp`** — Handle JSON-RPC requests
* **`tools/list`** — Return available tools with name, description, and input schema
* **`tools/call`** — Execute a tool and return the result

### Minimal server example (Node.js)

```typescript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "my-tools", version: "1.0.0" });

server.tool("lookup_user", { userId: z.string() }, async ({ userId }) => {
  const user = await db.users.findById(userId);
  return { content: [{ type: "text", text: JSON.stringify(user) }] };
});

// Mount on your Express/Fastify app at POST /mcp
```

### Authentication

If `mcpToolsApiKey` is set, Animam sends it as a Bearer token:

```
Authorization: Bearer your-bearer-token
```

Your server should validate this header and reject unauthenticated requests.

## Debugging

If tools don't appear in chat:

1. Check that `mcpToolsUrl` is reachable from the Animam API server
2. Verify your server responds to `tools/list` with valid tool definitions
3. Check that `mcpToolsMaxTools` is high enough to include your tools
4. Tools are cached — wait 5 minutes or restart the chat session
5. Verify your plan is Builder or above