MCP Tools

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.

Requires Builder plan or above. Your MCP server must support Streamable HTTP transport.

How it works

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

GET /tenants//mcp-tools

Read current MCP tools configuration. Required scope: settings:read

Request

curl https://api.animam.ai/tenants/my-company/mcp-tools \
  -H "Authorization: Bearer ak_your_token"

Response

{
  "mcpToolsUrl": "https://mcp.example.com/mcp",
  "mcpToolsMaxTools": 10,
  "hasApiKey": true
}

PUT /tenants//mcp-tools

Configure or update the external MCP server connection. Required scope: settings:write

Request

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

{
  "mcpToolsUrl": "https://mcp.example.com/mcp",
  "mcpToolsMaxTools": 10,
  "hasApiKey": true
}

DELETE /tenants//mcp-tools

Remove MCP tools configuration. Required scope: settings:write

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

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:

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

API Reference

Endpoints

How it works

GET /tenants//mcp-tools

Request

Response

PUT /tenants//mcp-tools

Request

Response

DELETE /tenants//mcp-tools

Configuration fields

MCP server requirements

Minimal server example (Node.js)

Authentication

Debugging

​How it works

​GET /tenants//mcp-tools

​Request

​Response

​PUT /tenants//mcp-tools

​Request

​Response

​DELETE /tenants//mcp-tools

​Configuration fields

​MCP server requirements

​Minimal server example (Node.js)

​Authentication

​Debugging

How it works

GET /tenants//mcp-tools

Request

Response

PUT /tenants//mcp-tools

Request

Response

DELETE /tenants//mcp-tools

Configuration fields

MCP server requirements

Minimal server example (Node.js)

Authentication

Debugging