Skip to content
Truto
Truto Blog
Back
AI & Agents

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

Learn how to connect Z.ai to claude using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Sidharth Verma Sidharth Verma · · 10 min read
Connect Z.ai to Claude: Parse Documents and Transcribe Audio

If your team uses ChatGPT, 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) like Claude the ability to interact with a multimodal AI suite like Z.ai creates a powerful compounding effect. Claude brings elite reasoning and orchestration capabilities, while Z.ai provides specialized, high-performance models for audio transcription (GLM-ASR-2512), high-fidelity video generation (CogVideoX), and advanced layout parsing for complex documents.

To connect these two systems securely, you need a Model Context Protocol (MCP) server. This server translates Claude's natural language tool calls into standard REST JSON-RPC requests that Z.ai understands. You can either build and maintain this infrastructure yourself, dealing with complex asynchronous polling loops and file handling, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

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 multimodal 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 specialized APIs is highly complex.

Z.ai is not a standard CRUD application. It is an orchestration engine for heavy compute tasks. If you decide to build a custom MCP server for Z.ai, here are the specific architectural hurdles you will face:

Asynchronous Job Polling and State Management Because tasks like generating video or transcribing long audio files take significant time, Z.ai relies heavily on asynchronous endpoints. When you call the video generation API, you do not get a video back - you get an id or request_id and a task_status. Your MCP server must either handle the polling logic internally, or explicitly expose a secondary polling tool and instruct Claude on how to use it. If the LLM does not understand that it needs to wait and check the status of async_id multiple times, workflows will fail silently.

Multimodal Payload Complexity Z.ai requires highly specific data formats for different endpoints. Layout parsing requires specific file formats, translation agents require terminology glossaries uploaded via specific multipart forms, and video generation requires exact first and last frame image dimensions. Abstracting these requirements into clean JSON Schemas that an LLM can understand without hallucinating parameters is a massive engineering effort.

Transparent Rate Limit Handling Heavy compute APIs like Z.ai enforce strict concurrency and rate limits. It is critical to understand how this is handled: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Z.ai upstream API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (in this case, your custom MCP client wrapper or Claude) is entirely responsible for implementing retry and backoff logic. Truto does not absorb these errors.

Instead of building out all this boilerplate, you can use Truto to instantly generate a managed MCP server that handles authentication, normalizes the schemas, and passes through rate limit data transparently.

How to Generate a Z.ai MCP Server with Truto

Truto's dynamic tool generation derives MCP tool definitions directly from Z.ai's API documentation and your environment's specific configuration. There are no static tool mappings to maintain.

Every MCP server is scoped to a single integrated account. The generated server URL contains a secure cryptographic token that encodes the account credentials, filters, and expiration policies.

You can create this server in two ways: via the Truto UI for rapid prototyping, or via the Truto API for programmatic deployment.

Method 1: Generating the Server via the Truto UI

For internal workflows or testing, the Truto interface provides the fastest path to a working MCP server.

  1. Navigate to the Integrated Accounts page in your Truto dashboard.
  2. Select your connected Z.ai account.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration (e.g., restrict to specific methods or tags).
  6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456...).

Method 2: Generating the Server via the API

For production use cases where you need to provision MCP servers dynamically for your own users, you should use the Truto API.

Make a POST request to /integrated-account/:id/mcp with your desired configuration.

curl -X POST https://api.truto.one/integrated-account/<z_ai_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Z.ai Multimodal Production Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API provisions the secure token infrastructure and returns a payload containing the exact URL needed to connect Claude.

{
  "id": "mcp_8a9b0c1d",
  "name": "Z.ai Multimodal Production Server",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8i9j0"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, connecting it to Claude is a straightforward process. You do not need to install local packages or deploy Docker containers. You can configure this via the Claude UI or through a manual configuration file.

Method A: Via the Claude UI (Desktop or Web)

Anthropic natively supports adding remote MCP servers directly through the Claude interface.

  1. Open Claude and navigate to Settings.
  2. Select the Integrations or Connectors tab.
  3. Click Add MCP Server or Add custom connector.
  4. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
  5. Click Add.

Claude will immediately perform a handshake with the Truto server, fetch the available Z.ai tools, and make them available in your chat interface.

Method B: Via Manual Configuration File (Claude Desktop)

If you are managing configurations programmatically or prefer the file-based approach, you can edit the claude_desktop_config.json file.

Because Truto exposes the MCP server over HTTP, you will use the official @modelcontextprotocol/server-sse transport adapter to connect.

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

Save the file and restart Claude Desktop. The tools will now appear as available integrations.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Zai as Z.ai API
    
    Claude->>Truto: POST /mcp/:token (initialize)
    Truto-->>Claude: Return Capabilities & Z.ai Tools
    Claude->>Truto: POST /mcp/:token (tools/call: create_a_z_ai_audio_transcription)
    Truto->>Zai: POST /v1/audio/transcriptions
    Zai-->>Truto: Return HTTP 200 (task ID)
    Truto-->>Claude: Return Tool Result (task ID)

Hero Tools for Z.ai

Truto dynamically maps Z.ai's capabilities into specific, actionable tools. Here are the highest-leverage tools available for Claude when connected to Z.ai.

Parse Document Layouts

"I just uploaded an annual report PDF. Use the Z.ai layout parsing tool to extract the text, identify the exact layout boundaries of the tables, and return the Markdown version of the document."

Tool: create_a_z_ai_paas_layout_parsing

This tool leverages the GLM-OCR model to perform advanced document parsing. Unlike standard text extractors, it returns deep structural data, including Markdown text (md_results), precise bounding boxes for elements (layout_details), and data attributes. It is incredibly useful for turning unstructured PDFs into structured inputs for Claude's analysis.

Transcribe Audio Files

"Take this MP3 of our customer interview and transcribe it using Z.ai. Return the raw text so I can summarize the key complaints."

Tool: create_a_z_ai_audio_transcription

This tool feeds audio into the GLM-ASR-2512 model. It supports multiple languages and handles complex audio environments. It returns the exact string output of the transcription, allowing Claude to read and process audio assets as if they were text documents.

Generate High-Fidelity Video

"Generate a 5-second video of a futuristic city at sunset using the prompt I just wrote. Initiate the Z.ai video generation task and give me the request ID."

Tool: create_a_z_ai_videos_generation

This tool triggers the CogVideoX or Vidu models. It supports text-to-video, image-to-video, and frame-to-video capabilities. Because video generation is computationally expensive, this tool does not return a video file. Instead, it returns a task_status and an id, requiring Claude to handle the asynchronous workflow.

Poll Asynchronous Results

"Check the status of the video generation task ID 'vid_987654'. If it is completed, give me the final video URL."

Tool: get_single_z_ai_paas_async_result_by_id

This is the critical companion tool to all of Z.ai's heavy compute endpoints. Claude uses this tool to check on the status of image generations, video generations, and complex agent tasks. Truto explicitly maps the required schemas so Claude knows exactly what id to pass to retrieve the final URL or error state.

"Run a web search using Z.ai to find the latest news on AI hardware releases this week, and summarize the top three articles based on the search summary."

Tool: create_a_z_ai_paas_web_search

Z.ai's web search API is explicitly designed for LLMs. Instead of returning raw HTML or cluttered SERP data, it returns highly structured intent-recognized data, including clean webpage titles, URLs, summaries, and site names, minimizing the token context Claude has to consume.

Generate Specialized Chat Completions

"Pass this complex reasoning prompt into the Z.ai chat completion tool using their latest model, and return the exact output choices."

Tool: create_a_z_ai_chat_completion

While Claude is the primary orchestrator, it can delegate specific sub-tasks to Z.ai's own models via this tool. This supports multimodal inputs (passing an image URL directly into the Z.ai model) and returns the standard completion choices.

To view the complete schema definitions, required parameters, and the full list of available endpoints, visit the Z.ai integration page.

Workflows in Action

By giving Claude access to Z.ai via Truto's MCP server, you transform a static chat interface into a multimodal agent capable of complex, multi-step execution. Here are two real-world workflows.

Scenario 1: The Automated Video Content Creator

Marketing teams frequently need to turn static audio assets (like podcasts) into visual social media content. Claude can orchestrate this entire pipeline by stringing Z.ai tools together.

"Transcribe this podcast clip using Z.ai. Read the transcript, identify the most dramatic quote, and use it as a prompt to generate a cinematic video using the Z.ai video generation tool. Check the status until the video is done, and give me the final URL."

  1. create_a_z_ai_audio_transcription: Claude sends the audio file URL to Z.ai's ASR model and receives the full text transcript.
  2. Internal Reasoning: Claude reads the transcript, identifies a strong quote, and writes a detailed visual prompt (e.g., "A cinematic slow-motion shot of a person looking inspired, neon lighting").
  3. create_a_z_ai_videos_generation: Claude submits the prompt to the video generation tool and receives a task ID (e.g., task_123).
  4. get_single_z_ai_paas_async_result_by_id: Claude polls the async endpoint. If it returns processing, Claude waits and calls it again. Once it returns completed, Claude extracts the final video URL and presents it to the user.

Scenario 2: The Deep-Research Document Analyst

Financial analysts often need to cross-reference unstructured PDF data (like earning reports) with current market news. Claude can handle both data extraction and web research seamlessly.

"Parse the uploaded Q3 earnings PDF to extract the revenue tables. Then, use the Z.ai web search tool to find news articles about this company from the last 7 days. Compare the PDF revenue numbers against the public sentiment in the news and write a brief summary."

  1. create_a_z_ai_paas_layout_parsing: Claude submits the PDF to the GLM-OCR model. Z.ai returns the md_results and structured table layouts.
  2. create_a_z_ai_paas_web_search: Claude uses the company name extracted from the PDF to trigger an LLM-optimized web search, retrieving clean summaries of recent news.
  3. Internal Reasoning: Claude synthesizes the Markdown data from the document parsing tool with the current news summaries retrieved from the web search tool, delivering a final analytical brief to the user.
flowchart TD
    A["User Prompt:<br>Parse PDF and search news"] --> B["Claude Engine"]
    B --> C["create_a_z_ai_paas_layout_parsing"]
    C --> D["Extract Markdown & Tables"]
    D --> B
    B --> E["create_a_z_ai_paas_web_search"]
    E --> F["Retrieve LLM-Optimized News"]
    F --> B
    B --> G["Final Synthesis & Response"]

Security and Access Control

Exposing an orchestration suite like Z.ai to an autonomous agent requires strict security boundaries. Truto provides multiple layers of control at the MCP server level to ensure Claude only accesses what it is allowed to.

  • Method Filtering: You can restrict an MCP server to only allow read operations or specific operations like create. If you only want Claude to transcribe audio but never spend credits generating video, you can enforce this at the token level.
  • Tag Filtering: Truto allows you to filter available tools by functional tags. You can generate an MCP server that only exposes Z.ai's translation tools, hiding all image and video generation endpoints entirely.
  • Secondary Authentication (require_api_token_auth): For enterprise environments, the MCP URL alone is not enough. Enabling this flag requires the MCP client to also pass a valid Truto API token in the Authorization header, ensuring only verified internal systems can interact with the server.
  • Automated Expiry (expires_at): If you are providing temporary access for a contractor or a specific automated run, you can set an ISO datetime. Once reached, Truto automatically cleans up the token from storage and invalidates the server.

Wrapping Up

Connecting Claude to Z.ai bridges the gap between elite reasoning and specialized multimodal execution. By using Truto to generate your MCP server, you completely bypass the grueling work of writing API wrappers, managing JSON Schemas, and handling authentication state.

Your engineers can stop building boilerplate tool schemas and focus on designing the agent logic and prompts that actually drive business value.

More from our Blog