Skip to main content

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.

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

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

FieldTypeRequiredDescription
mcpToolsUrlstringYesYour MCP server URL. Must be HTTPS.
mcpToolsApiKeystringNoBearer token sent to your server. Encrypted at rest (AES-256-GCM).
mcpToolsMaxToolsnumberNoMax 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:
  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