Connect ElizaOS to Claude: Automate agent runs and speech synthesis

If you need to connect ElizaOS to Claude to orchestrate multi-agent runs, synthesize speech, or manage decentralized messaging jobs, you need a Model Context Protocol (MCP) server. This server translates Claude's natural language tool calls into ElizaOS's specific REST API operations. You can either spend weeks building, hosting, and managing this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds. If your team uses ChatGPT, check out our guide on connecting ElizaOS to ChatGPT or explore our broader architectural overview on connecting ElizaOS to AI Agents.

Giving a Large Language Model (LLM) read and write access to a specialized framework like ElizaOS is an orchestration challenge. You are essentially putting an AI model in charge of starting, stopping, and monitoring other AI agents. Every time ElizaOS updates its core endpoint structures or deprecates an agent control schema, a custom integration breaks.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for ElizaOS, connect it natively to Claude Desktop, and execute complex agentic workflows using natural language.

The Engineering Reality of the ElizaOS API

A custom MCP server is a self-hosted translation layer. While the open MCP standard provides a predictable way for Claude to discover tools via JSON-RPC 2.0, the reality of implementing it against the ElizaOS API requires careful architectural planning.

ElizaOS is not a standard B2B SaaS CRUD application. It is an operating system for agents, meaning its API is highly stateful, relies heavily on asynchronous operations, and frequently handles binary data payloads. If you build a custom MCP server for ElizaOS, here are the specific challenges you must solve:

Asynchronous Job Orchestration and Polling The ElizaOS API relies heavily on one-off messaging jobs. When you hit the create_a_eliza_os_job endpoint, it expects payloads up to 50KB and can run with a timeoutMs of up to 300,000 milliseconds (5 minutes). This means the API often does not return the final result immediately. Instead, it returns a jobId. To expose this to Claude, your MCP server must handle the initial response and allow Claude to poll get_single_eliza_os_job_by_id until the completedAt timestamp is populated. If you fail to design this correctly, Claude will assume the job failed or enter a hallucination loop trying to invent the job output.

Binary Audio Data Delivery ElizaOS includes powerful built-in text-to-speech (TTS) and speech-to-text capabilities. However, endpoints like eliza_os_audio_generate_speech and eliza_os_audio_synthesize_speech return raw binary data - specifically audio/mpeg files. LLMs and the MCP JSON-RPC protocol communicate in JSON. If you pass raw binary buffers back through an unmanaged MCP server, the protocol crashes. A managed integration layer properly encodes or links this binary output so Claude can acknowledge the successful file generation without breaking the JSON parser.

Hierarchical Dependency Constraints ElizaOS uses a deeply nested architectural model. Agents exist within Worlds, Worlds contain Rooms, Rooms contain Memories, and a parallel structure exists for Messaging Servers and Channels. You cannot simply create a channel without knowing the serverId, and you cannot add an agent to a room without the agent_id. If Claude is given unmanaged access to these endpoints, it will frequently fail by guessing UUIDs. Truto solves this by extracting the integration's actual API format into dynamic, heavily documented JSON schemas. The tool definitions force Claude to gather the correct IDs sequentially.

Handling Rate Limits at the Edge ElizaOS enforces rate limits to prevent runaway agent loops. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream ElizaOS API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This guarantees that your local Claude instance or custom agent orchestration logic receives accurate, real-time feedback and can apply its own specific backoff strategies without silent failures in the proxy layer.

sequenceDiagram
    participant Claude as Claude Desktop
    participant TrutoMCP as Truto MCP Server
    participant ElizaOS as ElizaOS API

    Claude->>TrutoMCP: tools/call (create_a_eliza_os_job)
    TrutoMCP->>ElizaOS: POST /api/jobs
    ElizaOS-->>TrutoMCP: 200 OK (jobId: "xyz-123", status: "pending")
    TrutoMCP-->>Claude: Tool Result (jobId: "xyz-123")
    
    Note over Claude: Claude decides to wait,<br>then poll for status
    
    Claude->>TrutoMCP: tools/call (get_single_eliza_os_job_by_id)
    TrutoMCP->>ElizaOS: GET /api/jobs/xyz-123
    ElizaOS-->>TrutoMCP: 429 Too Many Requests
    TrutoMCP-->>Claude: Error (HTTP 429, ratelimit-reset: 60)
    
    Note over Claude: Claude applies backoff<br>based on headers

How to Generate an ElizaOS MCP Server with Truto

Instead of writing and maintaining thousands of lines of TypeScript to map ElizaOS schemas to MCP tools, you can use Truto. Truto dynamically generates tool definitions by deriving them directly from the integration's documented API endpoints.

You can generate your ElizaOS MCP server using either the Truto UI or the Truto REST API. Both methods output a secure, authenticated URL containing a cryptographic token.

Method 1: Generating via the Truto UI

This is the fastest method for interactive development and testing.

1. Log in to your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected ElizaOS account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter tools by methods (e.g., allow only read operations) or apply tags to group functional areas.
6. Copy the generated MCP server URL. It will look like this: https://api.truto.one/mcp/a1b2c3d4e5f6...

Method 2: Generating via the API

For production workflows or automated provisioning, you can generate MCP servers programmatically using your Truto API token.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ElizaOS Automation Server",
    "config": {
      "methods": ["read", "write", "custom"],
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The Truto API will validate the configuration, confirm that ElizaOS tools are available, and return a database record containing your ready-to-use URL.

How to Connect the MCP Server to Claude

Once you have your Truto MCP server URL, you must add it to Claude. Because Truto handles the tool derivation dynamically, you only need to provide the URL - Claude will automatically perform the JSON-RPC initialization handshake and discover the available ElizaOS tools.

Method A: Via the Claude UI

If you are using Claude Desktop or an enterprise deployment that supports UI-based custom connectors, you can add it directly.

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server (or Add custom connector depending on your version tier).
3. Provide a name (e.g., "ElizaOS Prod").
4. Paste the Truto MCP server URL you copied earlier.
5. Click Add or Save. Claude will immediately index the tools.

Method B: Via the Manual Configuration File

For developers running Claude Desktop locally, you can modify the claude_desktop_config.json file. This method utilizes the official @modelcontextprotocol/server-sse package to connect to Truto's remote endpoint via Server-Sent Events.

Open your configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following:

{
  "mcpServers": {
    "elizaos-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The initialization sequence will fetch the exact query schemas, body schemas, and descriptions required to operate the ElizaOS API.

Hero Tools for ElizaOS

Truto exposes the entirety of the ElizaOS integration as tools. When Claude invokes these tools, the arguments are parsed into the correct query or body parameters dynamically. Here are the highest-leverage tools available for ElizaOS automation.

eliza_os_audio_generate_speech

Generates speech from text for a specific ElizaOS agent. This tool bridges the gap between text-based orchestration and audio output, returning an audio/mpeg file representing the requested text.

"Generate an audio file for agent 8f9b2c using the text: 'System diagnostics complete. All asynchronous jobs are currently healthy.'"

create_a_eliza_os_agent

Creates a new agent in ElizaOS from either a character path or an inline JSON object. This is the foundational tool for dynamically scaling your agent workforce.

"Create a new ElizaOS agent using the following character JSON. Name it 'DevOps Monitor' and configure its system prompt to analyze server metrics."

eliza_os_agents_start

Starts a specific ElizaOS agent that is currently stopped. It returns the started agent object, including its updated operational status.

"Start the DevOps Monitor agent (id: e3a1f4) and confirm its status has changed to active."

create_a_eliza_os_job

Creates a one-off messaging job in ElizaOS. This tool handles complex asynchronous workloads. It requires a userId and content (max 50KB) and returns a jobId for subsequent polling.

"Create a messaging job for user u-778899 to process the attached log file content. Set the timeout to 120000ms."

eliza_os_messaging_channels_send_message

Sends a message to a specific ElizaOS messaging channel. This requires the channel_id, author_id, content, and the message_server_id.

"Send a message to the incident-response channel (id: c-456) on server s-123 stating that the primary database is experiencing high latency. Make the author ID my admin UUID."

eliza_os_memory_create_room

Creates a room for an ElizaOS agent, allowing you to isolate context and memory persistence for specific workflows.

"Create a new memory room named 'Q4 Planning Strategy' for agent 8f9b2c. Let me know the room ID once it is created."

This is only a subset of the available operations. For the complete tool inventory, including detailed JSON schemas, parameter requirements, and deprecation notes, visit the ElizaOS integration page.

Workflows in Action

Once connected, Claude can string together multiple ElizaOS tool calls to accomplish complex, multi-step tasks without any hardcoded scripts.

Workflow 1: Voice-Agent Provisioning

In this scenario, a user wants to provision a brand new agent, spin it up, and immediately verify its text-to-speech capabilities.

"Create a new agent named 'GreeterBot' with a friendly system prompt. Once created, start the agent. Finally, generate speech for this new agent saying 'Hello, I am online and ready to assist'."

Step-by-step execution:

1. Claude calls create_a_eliza_os_agent passing the required name and inline JSON configuration for the system prompt.
2. Claude extracts the id from the resulting payload.
3. Claude calls eliza_os_agents_start using the extracted id to boot the agent.
4. Claude calls eliza_os_audio_generate_speech passing the same id and the requested text.

Result: The user receives confirmation that the agent was created and started, along with the generated audio/mpeg speech asset, all in one seamless conversation flow.

Workflow 2: Messaging Job Orchestration

In this scenario, a developer needs to push a large chunk of data into ElizaOS for asynchronous processing and wants Claude to monitor the result.

"Submit a messaging job for user 4b5c6d containing the following system report data. Wait for the job to complete and tell me the final status and result."

Step-by-step execution:

1. Claude calls create_a_eliza_os_job passing the userId and the report content.
2. Claude receives the jobId and notes the status is likely "pending".
3. Claude waits briefly, then calls get_single_eliza_os_job_by_id using the jobId.
4. If the job is still processing, Claude might poll again based on the provided createdAt and expiresAt limits.
5. Once completedAt is populated, Claude extracts the result.

Result: Claude orchestrates the asynchronous workflow autonomously, ultimately summarizing the finalized job output for the user without requiring the user to manually track the job queue.

Security and Access Control

Exposing an autonomous agent framework to an LLM requires strict governance. Truto's MCP servers provide granular access controls built directly into the server generation process.

• Method Filtering: You can restrict a server to specific HTTP operation types via config.methods. Passing ["read"] ensures Claude can only call GET or LIST endpoints (e.g., listing agents or reading logs), preventing any accidental data mutation or agent destruction.
• Tag Filtering: Integration endpoints in Truto are tagged by functional area. You can restrict an MCP server to only expose tools matching specific tags via config.tags (e.g., exposing only messaging tools while hiding billing or infrastructure tools).
• API Token Authentication: By default, possession of the MCP URL is sufficient to connect. For enterprise deployments, you can set require_api_token_auth: true. This forces Claude (or any client connecting to the URL) to also provide a valid Truto API token in the Authorization header, adding a strict second layer of identity verification.
• Automatic Expiration: You can provision short-lived access by defining an expires_at timestamp. Once the timestamp passes, the server and its cryptographic tokens are permanently destroyed, instantly revoking Claude's access to the ElizaOS environment.

Wrap-up

Connecting ElizaOS to Claude shouldn't require maintaining a custom middleware layer to handle polling logic, binary audio streams, and deeply nested object schemas. By using Truto's documentation-driven MCP generation, you can expose ElizaOS's entire API surface to Claude in minutes. Your AI agents get real-time read and write capabilities, and your engineering team avoids owning the integration lifecycle.