Connect Z.ai to Claude: Process Documents and Transcribe Audio

If you need to connect Z.ai to Claude to process complex documents, transcribe audio, or generate multimodal content, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Z.ai's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses OpenAI models, check out our guide on connecting Z.ai to ChatGPT or explore our broader architectural overview on connecting Z.ai to AI Agents.

Giving a Large Language Model (LLM) read and write access to a multimodal API like Z.ai is an engineering challenge. You have to handle complex asynchronous polling logic, map strict JSON schemas for file handling, and deal with Z.ai's specific rate limits. Every time Z.ai updates an endpoint or releases a new foundational model, 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 Z.ai, connect it natively to Claude, and execute complex workflows using natural language.

The Engineering Reality of the Z.ai API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Z.ai's specific architecture requires solving several non-trivial problems.

If you decide to build a custom MCP server for Z.ai, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Execution and Polling Orchestration Unlike standard CRUD APIs where a request immediately returns a mutated record, Z.ai relies heavily on asynchronous processing for heavy workloads. Operations like video generation (create_a_z_ai_videos_generation) or complex layout parsing do not return the final result. Instead, they return a task ID. Your MCP server must expose both the creation endpoint and the polling endpoint (get_single_z_ai_paas_async_result_by_id). If you do not explicitly prompt Claude on how to handle this duality, the agent will hallucinate results instead of waiting. Truto handles the schema generation that instructs the LLM on exactly what these fields mean, ensuring Claude knows it must poll the async result endpoint using the returned ID.

Polymorphic Response Schemas Z.ai's async polling endpoint is polymorphic. A single endpoint (/v1/async-result/{id}) returns entirely different data structures depending on the task type. If the original task was image generation, it returns an AsyncImageGenerationResponse. If it was video, it returns an AsyncVideoGenerationResponse. Writing a static schema for this in a custom MCP server often results in validation errors when the LLM receives unexpected keys. Truto dynamically merges and maps these schemas directly from Z.ai's underlying documentation, providing Claude with a unified, accurate JSON Schema that accommodates these varied response shapes.

Rate Limits and 429 Passthrough Z.ai enforces strict rate limits, especially on compute-heavy models like GLM-4V or CogVideoX. If your agent attempts to batch-process 50 document layout parsing requests in parallel, Z.ai will return HTTP 429 (Too Many Requests). A critical architectural detail: Truto does not retry, throttle, or absorb these rate limits on your behalf. When Z.ai returns a 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This allows you to program Claude's system prompt or underlying framework (like LangGraph) to read these standardized headers and execute intelligent exponential backoff, rather than failing silently.

How to Generate a Z.ai MCP Server with Truto

Truto dynamically generates MCP servers based on the documented resources of your connected Z.ai account. The server is scoped strictly to the tenant's credentials, meaning the resulting URL is fully self-contained.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For quick testing or internal IT workflows, you can generate the MCP server directly from the dashboard.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Z.ai account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server. You can restrict the server to specific operations (e.g., only "read" methods) or specific tags (e.g., "transcription").
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For production deployments where you are provisioning AI agents programmatically, you should generate the MCP server via the Truto REST API.

Make a POST request to /integrated-account/:id/mcp. You can pass configuration filters in the body to restrict the LLM's access.

curl -X POST https://api.truto.one/integrated-account/<z_ai_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Z.ai Document Processing",
    "config": {
      "methods": ["read", "create", "custom"]
    },
    "expires_at": "2026-12-31T00:00:00Z"
  }'

The API validates that the Z.ai integration has tools available, generates a cryptographically secure token, stores it in the edge infrastructure, and returns a ready-to-use URL.

{
  "id": "mcp_8a9b2c",
  "name": "Z.ai Document Processing",
  "config": { "methods": ["read", "create", "custom"] },
  "expires_at": "2026-12-31T00:00:00Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with Claude. You can do this via the Claude Desktop UI for personal/team use, or via the claude_desktop_config.json file for automated local environments.

Method A: Via the Claude UI

1. Open Claude Desktop (or the web interface, if applicable to your tier).
2. Navigate to Settings > Integrations > Add MCP Server (Note: Interface paths may vary slightly between Claude and ChatGPT, but the custom connector logic remains identical).
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add.

Claude will immediately perform a handshake with the Truto server, execute a tools/list JSON-RPC call, and dynamically load the available Z.ai tools.

Method B: Via Manual Config File

If you are managing Claude Desktop environments programmatically, you can inject the server directly into the configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

Because Claude Desktop expects local executables for custom servers, you use the official @modelcontextprotocol/server-sse package to proxy the remote Truto URL.

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

Save the file and restart Claude Desktop. The agent will now have full access to the defined Z.ai toolset.

Z.ai Hero Tools for Claude

Truto automatically generates precise, schema-backed tools from Z.ai's endpoints. Here are the highest-leverage tools your AI agent can use to orchestrate Z.ai.

create_a_z_ai_chat_completion

This is the core execution tool for Z.ai's GLM foundational models. It supports multimodal inputs (text, image, video, files) and handles function calling. Claude uses this when it needs to delegate a specific reasoning or generation task to Z.ai's specialized models.

Usage Note: The schema requires the model and messages array. Claude must properly format the nested content blocks if sending image URLs.

"Use the Z.ai chat completion tool with the GLM-4V model. Pass it this image URL and ask it to extract the brand colors and typography rules into a JSON object."

create_a_z_ai_paas_layout_parsing

Submits a layout parsing request using the GLM-OCR model. This tool extracts text content and spatial layout information from dense document images or PDFs, returning markdown results and layout coordinates.

Usage Note: This tool is critical for RAG pipelines processing complex enterprise PDFs. It returns immediate results for smaller files, but Claude must be prepared to handle large payloads in the response.

"Take this PDF invoice file and run it through the Z.ai layout parsing tool. Extract all line items into a structured table, ensuring you preserve the column headers exactly as they appear in the visual layout."

create_a_z_ai_audio_transcription

Transcribes audio files into text using the GLM-ASR-2512 model. It supports multiple languages and returns highly accurate text blocks.

Usage Note: The LLM must provide the model identifier and the audio payload. Claude can use this to process meeting recordings before summarizing them.

"Send the attached MP3 of the Q3 earnings call to the Z.ai audio transcription tool. Once you get the transcript back, summarize the key financial risks mentioned by the CFO."

create_a_z_ai_videos_generation

Creates a video generation task in Z.ai using CogVideoX or Vidu models. This handles text-to-video, image-to-video, and first/last-frame workflows.

Usage Note: This is an asynchronous operation. Calling this tool returns an id and a task_status. Claude must not invent the video output; it must capture the ID for the next step.

"I need a 5-second marketing video. Use the Z.ai video generation tool. The prompt is: 'A futuristic sports car driving through a neon-lit cyberpunk city at night, 4k, hyperrealistic.' Give me the task ID when it is submitted."

get_single_z_ai_paas_async_result_by_id

The required companion tool for any asynchronous Z.ai task. Claude uses this to poll for the status and final output of video, image, or agent generation tasks.

Usage Note: The LLM should be instructed in its system prompt to wait a few seconds between calls to this tool to avoid spamming the API and triggering a 429 rate limit.

"Check the status of task ID 'vid_987654321' using the async result tool. If it is still processing, wait 10 seconds and check again. Once successful, give me the final video URL."

create_a_z_ai_paas_web_search

Performs an LLM-optimized web search. Z.ai's search API enhances intent recognition and returns data formatted specifically for large language model ingestion (titles, URLs, summaries, site names).

Usage Note: Claude can use this to enrich its context window with real-time data before executing a final reasoning step.

"Run a Z.ai web search for 'Recent regulatory changes in European AI act 2026'. Compile the summaries from the top 3 results and draft a memo on how it impacts SaaS compliance."

For the complete tool inventory and granular JSON Schema details, visit the Z.ai integration page.

Workflows in Action

Giving Claude individual tools is useful, but the real power of MCP emerges when the LLM chains multiple tools together to solve complex problems autonomously. Here are two concrete workflows specific to the Z.ai ecosystem.

Workflow 1: The Automated Earnings Call Analyst

Financial analysts spend hours listening to earnings calls and cross-referencing statements with market news. By connecting Claude to Z.ai, this entire process can be automated using specialized multimodal models.

"Take this MP3 file of the Acme Corp Q3 earnings call. Transcribe it using Z.ai. Then, run a Z.ai web search for 'Acme Corp Q3 market reaction'. Finally, use the Z.ai chat completion tool with GLM-4 to analyze the transcript against the web search results, identifying discrepancies between executive sentiment and market reality."

Execution Steps:

1. Claude calls create_a_z_ai_audio_transcription with the audio file and GLM-ASR-2512 model.
2. Z.ai returns the raw transcription text.
3. Claude calls create_a_z_ai_paas_web_search with the query "Acme Corp Q3 market reaction".
4. Z.ai returns structured search results and summaries.
5. Claude formulates a prompt combining the transcript and search results, and calls create_a_z_ai_chat_completion using the GLM-4 model to perform the final deep analysis.
6. Claude presents the final analytical report to the user.

sequenceDiagram
  participant User as User
  participant Claude as Claude Desktop
  participant MCP as Truto MCP Server
  participant Upstream as Z.ai API

  User->>Claude: "Transcribe call, search market reaction, analyze..."
  Claude->>MCP: Call create_a_z_ai_audio_transcription
  MCP->>Upstream: POST /v1/audio/transcriptions
  Upstream-->>MCP: 200 OK (Transcript)
  MCP-->>Claude: Return text
  Claude->>MCP: Call create_a_z_ai_paas_web_search
  MCP->>Upstream: POST /v1/web/search
  Upstream-->>MCP: 200 OK (Results)
  MCP-->>Claude: Return search data
  Claude->>MCP: Call create_a_z_ai_chat_completion
  MCP->>Upstream: POST /v1/chat/completions
  Upstream-->>MCP: 200 OK (Analysis)
  MCP-->>Claude: Return final analysis
  Claude->>User: Present Financial Report

Workflow 2: Asynchronous Video Asset Generation

Marketing teams often need b-roll or concept videos quickly. Because video generation is computationally expensive, it requires asynchronous polling. Claude handles this orchestration natively via MCP.

"I need a background video for our new cybersecurity product launch. Submit a video generation task to Z.ai with the prompt 'Abstract glowing blue network nodes connecting in a dark digital space'. Check the status until it's done, then give me the download URL."

Execution Steps:

1. Claude calls create_a_z_ai_videos_generation with the prompt and the CogVideoX model.
2. Z.ai returns a task id and a status of "Processing".
3. Claude pauses, then calls get_single_z_ai_paas_async_result_by_id using the returned ID.
4. Z.ai returns a 200 OK, but the payload shows task_status: "Processing".
5. Claude loops, waiting a few seconds, then calls the polling tool again.
6. Z.ai returns a 200 OK with task_status: "Success" and the final video URL.
7. Claude outputs the direct link to the user.

Security and Access Control

When connecting an enterprise AI agent to a powerful platform like Z.ai, security and spend management are critical. You do not want a rogue LLM looping 10,000 video generation requests and draining your API credits. Truto provides several mechanisms to lock down your MCP server:

• Method Filtering: When generating the server, configure config.methods to ["read"] if you only want Claude to perform web searches or query existing tasks. Exclude "create" to prevent the LLM from executing costly generative operations.
• Tag Filtering: Use config.tags to group tools. You can restrict an MCP server to only expose tools tagged with ["transcription"], entirely hiding the video and chat completion endpoints from the agent.
• Secondary Authentication (require_api_token_auth): By default, possessing the MCP URL grants access to the tools. Setting this flag to true forces the MCP client to also pass a valid Truto API token in the Authorization header, ensuring only authenticated systems can invoke the Z.ai resources.
• Automatic Expiration (expires_at): For temporary workflows - like giving a contractor access to Z.ai via their local Claude instance for a specific project - set an ISO datetime. Truto will automatically revoke the token and destroy the edge storage records at that exact moment.

Moving Past Manual Integration

Connecting Claude to Z.ai opens up massive potential for automating multimodal data processing. But building a custom MCP server means owning the burden of polling logic, schema translation, and error normalization. Z.ai's dynamic, asynchronous architecture makes this exceptionally difficult to maintain in-house.

Truto abstracts this away. By deriving MCP tools directly from live API documentation, handling the strict JSON-RPC protocol, and normalizing rate limit headers, Truto lets your engineering team focus on building AI capabilities rather than maintaining REST wrappers.