Connect World to Claude: Manage World ID Accounts and Recovery

If you need to connect World to Claude to automate World ID verifications, manage MiniKit apps, or orchestrate on-chain account recovery, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and the World developer APIs. You can either spend weeks building and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting World to ChatGPT or explore our broader architectural overview on connecting World to AI Agents.

Giving a Large Language Model (LLM) read and write access to a decentralized identity ecosystem like World is a serious engineering challenge. You have to handle cryptographic commitments, navigate asynchronous on-chain state changes, and map complex nested JSON schemas to MCP tool definitions. Every time World updates a gateway endpoint or changes a signature requirement, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for World, connect it natively to Claude, and execute complex identity and recovery workflows using natural language.

The Engineering Reality of the World API

A custom MCP server is a self-hosted integration layer that translates an LLM's natural language intent into strictly formatted JSON-RPC messages, and ultimately into REST API requests. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against the World API is uniquely painful.

If you decide to build a custom World MCP server, you own the entire integration lifecycle. Here are the specific challenges you will face when working with World's infrastructure:

Asynchronous Gateway Polling Many of World's critical operations - such as creating an account (create_a_world_create_account), recovering an account (create_a_world_recover_account), or updating an authenticator - do not resolve immediately. Because these operations interact with on-chain smart contracts (the WorldIDRegistry), the API gateway returns an HTTP 202 Accepted response with a request_id. You cannot simply pass a 202 back to Claude and expect it to understand the job is done. Your agent needs a deterministic way to poll the gateway using the request_id until the transaction resolves or fails. Exposing these dual endpoints correctly so the LLM knows to wait and verify is a complex prompt engineering task.

Cryptographic Precision and Hex Encodings World APIs require highly specific cryptographic payloads. Fields like offchain_signer_commitment, nullifier_hash, and authenticator_pubkeys are not standard strings. They often require precise 0x-prefixed hexadecimal formatting or specific decimal representations. If you expose raw, unconstrained parameters to Claude, the model will frequently hallucinate invalid hex strings or misunderstand the required padding. A managed MCP server provides strict JSON schemas that instruct the LLM exactly how to format these cryptographic commitments.

Merkle Tree State and Leaf Indices In standard SaaS APIs, you query a user by a UUID or email address. In the World ecosystem, users are often identified by their position in a Merkle tree - the leaf_index. To perform an operation like initiating a recovery agent update, the agent first has to query the indexer to find the user's current leaf_index, retrieve their current signature nonce, and then submit the update. This requires multi-step state management that must be perfectly orchestrated by the MCP tool definitions.

Strict Rate Limiting Mechanics World enforces rate limits on its endpoints, particularly heavy indexer queries and MiniKit notification broadcasts. It is critical to understand how this is handled: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream World API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - your AI agent or orchestrator framework - is entirely responsible for reading the ratelimit-reset header and implementing proper exponential backoff.

Instead of building a bespoke server to handle these quirks, you can use Truto. Truto derives tool definitions directly from the World API documentation, enforcing schema correctness and exposing complex asynchronous flows as ready-to-use MCP tools.

Generating the World MCP Server

Truto creates MCP servers dynamically based on your connected integrations. The tool generation is documentation-driven - Truto automatically parses the World API resources, derives the query and body schemas, and surfaces them as JSON-RPC 2.0 endpoints.

Each MCP server is scoped to a single integrated account. This means the server URL contains a cryptographic token that securely encodes which World account to use, ensuring zero credential leakage to the LLM client. You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

If you are setting up Claude Desktop for internal administrative use, the easiest way to generate the server is through the Truto dashboard.

1. Log into your Truto environment and navigate to your connected World integrated account.
2. Click on the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server. You can optionally filter by methods (e.g., selecting only read methods to prevent Claude from executing state-changing transactions) or filter by tags to restrict access to specific resource groups.
5. Click Save. Truto will generate a secure MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...). Copy this URL.

Method 2: Via the Truto API

For enterprise teams deploying AI agents dynamically, you can generate MCP servers on the fly using the Truto API. This is ideal when provisioning dedicated agent environments for different developers or automated workflows.

Make a POST request to the /integrated-account/:id/mcp endpoint:

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

The API will validate that the World integration has active tools, generate a hashed token, store it in Cloudflare KV for fast reverse lookups, and return the server details:

{
  "id": "mcp-789-xyz",
  "name": "World Identity Management Agent",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890abcdef"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you need to register it with your LLM client. Because Truto's MCP servers are self-contained and authenticated via the token in the URL, the setup requires no extra environment variables or OAuth handshakes on the client side.

Option A: Via the Claude UI (or ChatGPT)

If you are using Anthropic's web interface or ChatGPT with custom connector support:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server (in ChatGPT, go to Settings -> Apps -> Advanced settings and enable Developer mode).
2. Provide a name for the connection (e.g., "World API Truto").
3. Paste the URL generated in the previous step.
4. Click Add or Save.

The LLM will immediately perform an MCP handshake, calling initialize and tools/list to discover all available World API operations.

Option B: Via the Claude Desktop Config File

If you are running Claude Desktop locally or configuring a headless agent framework like Cursor, you can register the server via your claude_desktop_config.json file. Truto provides an official remote MCP transport via npx.

Open your configuration file (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": {
    "world-api": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890abcdef"
      ]
    }
  }
}

Restart Claude Desktop. The application will boot, read the configuration, execute the server-side events command, and load the World tools into your context window.

World Hero Tools for Claude

Truto exposes the entirety of the World API as distinct MCP tools. By deriving these tools directly from the API documentation, Truto ensures that required fields, query parameters, and hex-encoding rules are strictly passed to the LLM. Below are the most critical operations you can execute via Claude.

create_a_world_verify

This tool allows the agent to verify a World ID proof for a Cloud action. The LLM must pass the verify_id to validate the zero-knowledge proof.

"I have a verification payload from a user attempting to claim a reward on our platform. The verification ID is req_8f7b2c9a. Can you run the verification check against the World API and tell me if the nullifier hash is unique and the action was successful?"

create_a_world_minikit_send_notification

Sends a push notification to users of your World mini app by their wallet address. The LLM can format localized content or standard messages and dispatch them to up to 1,000 wallet addresses per call.

"We just deployed an update to our MiniKit app (App ID: app_49b2c8a1). Send a notification to the wallet address 0x71C...34F with the title 'Update Complete' and the message 'Your new features are ready to use.'"

get_single_world_status_by_id

Because many World registry gateway requests (like account creation or authenticator removal) are processed asynchronously on-chain, they return a 202 Accepted. This tool allows the agent to poll the gateway using a request_id to determine the current state and retrieve the final transaction hash.

"I initiated a recovery update a few minutes ago and received the request ID req_49102ab. Can you check the current status of this gateway request and let me know if it has successfully executed on-chain?"

create_a_world_recover_account

Submits a recovery request to the registry gateway. The LLM must orchestrate the collection of the leaf_index, the new authenticator address, signer commitments, and the cryptographic signature before invoking this tool.

"A user has lost access to their primary device and needs to recover their account. Their leaf index is 49201. Submit a recovery request using their new authenticator address 0x38F...1A2 and the provided off-chain signer commitment. Provide me the request ID so we can poll for completion."

create_a_world_signature_nonce

Retrieves the current signature nonce for a World ID based on its leaf index. This is a prerequisite for executing any state-changing operations on the user's account.

"Before we insert a new authenticator for the user at leaf index 18420, we need their current nonce. Can you query the indexer for their signature nonce?"

list_all_world_miniapps_prices

Fetches the latest token prices in various fiat and crypto currencies from World. This is vital for MiniKit apps that process payments or display real-time values.

"Pull the latest token prices from the World API for USD and EUR against ETH and WLD. Format the response into a Markdown table so I can update our dashboard."

get_single_world_minikit_userop_by_id

Fetches a single MiniKit user operation by ID and resolves the final on-chain transaction hash when it becomes available. Crucial for tracking in-app transactions.

"A user attempted a transaction inside our MiniKit app with the user operation ID uop_992a11b. Look up this operation and return the final on-chain transaction hash and the sender address."

For the complete list of available tools, query schemas, and required parameters, consult the World integration page.

Workflows in Action

Exposing individual endpoints to an LLM is useful, but the true power of MCP lies in giving Claude the ability to orchestrate complex, multi-step operations autonomously.

Scenario 1: Verifying a Proof and Notifying the User

In this scenario, a decentralized application administrator wants Claude to process a pending World ID proof and immediately notify the user via their MiniKit app.

"We received a World ID verification payload for a user claiming an airdrop. The verify ID is vrf_883a2b. Please run the verification. If it returns success, immediately send a notification to their wallet 0x42A...9C1 (App ID app_prod_99) saying 'Verification successful, your tokens are on the way'."

1. Verify Proof: Claude calls create_a_world_verify with verify_id: "vrf_883a2b".
2. Evaluate Response: Claude parses the response. It checks if success is true and extracts the nullifier_hash.
3. Send Notification: Seeing a successful verification, Claude invokes create_a_world_minikit_send_notification passing the app_id, the wallet_addresses array, and the title/message payload.
4. Final Output: Claude responds to the user: "The verification was successful. I have dispatched the notification to the user's wallet address."

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant World as World API

    User->>Claude: "Verify proof vrf_883a2b and notify wallet"
    Claude->>Truto: call tool: create_a_world_verify (vrf_883a2b)
    Truto->>World: POST /api/v2/verify/vrf_883a2b
    World-->>Truto: 200 OK { success: true }
    Truto-->>Claude: JSON-RPC Result
    Claude->>Truto: call tool: create_a_world_minikit_send_notification
    Truto->>World: POST /api/v1/minikit/notify
    World-->>Truto: 200 OK
    Truto-->>Claude: JSON-RPC Result
    Claude-->>User: "Verification successful, notification sent."

Scenario 2: Initiating and Resolving Account Recovery

Handling on-chain recovery requires coordinating indexer lookups with asynchronous gateway operations. Claude can manage this state natively.

"A user at leaf index 55210 needs account recovery. Get their current signature nonce, then submit a recovery request using their new authenticator 0x99B...2A1 and this signature payload. Keep checking the gateway status until the transaction is confirmed."

1. Fetch Nonce: Claude calls create_a_world_signature_nonce with leaf_index: "55210" to retrieve the current nonce.
2. Submit Recovery: Claude formulates the payload using the fetched nonce and calls create_a_world_recover_account.
3. Extract Request ID: The API returns an HTTP 202 with a request_id (e.g., req_881b2).
4. Poll Gateway: Claude autonomously enters a loop, calling get_single_world_status_by_id with id: "req_881b2".
5. Resolve: Once the status returns as executed with a tx_hash, Claude outputs the final transaction hash to the user.

flowchart TD
    A["Claude calls<br>create_a_world_signature_nonce"] --> B["World API returns<br>current nonce"]
    B --> C["Claude calls<br>create_a_world_recover_account"]
    C --> D["World API returns 202<br>with request_id"]
    D --> E["Claude calls<br>get_single_world_status_by_id"]
    E --> F{"Status == executed?"}
    F -->|"No (Pending)"| E
    F -->|"Yes"| G["Claude returns tx_hash<br>to user"]

Security and Access Control

Connecting an LLM to a system that manages cryptographic identity requires rigorous access control. Truto's MCP server architecture is designed around security primitives that keep your World data safe:

• Method Filtering: During MCP server creation, you can strictly limit the server to specific method categories. For example, setting methods: ["read"] ensures the agent can query leaf indices and statuses but physically cannot execute a create or update operation that mutates on-chain state.
• Tag Filtering: You can restrict the MCP server to only expose tools associated with specific resource tags, ensuring Claude only sees the subset of the World API necessary for its specific task (e.g., only exposing MiniKit APIs and hiding core identity APIs).
• Token Authentication: The MCP server URL contains a hashed token. The raw token is never stored in Truto's database. If you require higher security, you can enable require_api_token_auth, which forces the client to pass a valid Truto API token in the Authorization header, preventing unauthorized access even if the URL is leaked.
• Automatic Expiration: For temporary agent access, you can set an expires_at timestamp. Cloudflare KV handles the TTL, and a Durable Object alarm ensures all database records and KV entries are hard-deleted the moment the token expires.

Accelerate Your AI Agent Architecture

Connecting World to Claude manually means writing custom pagination handlers, managing complex hex-encoded schemas, and writing brittle polling loops for async gateway requests. Truto abstracts this away, turning the entire World Developer API into a robust, LLM-ready MCP server in seconds.

By normalizing the API layer, Truto allows your engineering team to focus on building intelligent agent workflows rather than maintaining point-to-point connector code. The LLM gets exactly the context it needs, strictly formatted according to World's specifications.