Wiro MCP Server

Official MCP server for Wiro AI — access all AI models on Wiro from Cursor, Claude, Windsurf, and any MCP-compatible AI assistant.

Official MCP Server · Self-Hosted MCP · Models · Dashboard · Docs

Quick Start

Local npx and library usage require Node.js 20 or later. The hosted MCP
endpoint does not require a local Node.js installation.

1. Get API Keys

Sign up at wiro.ai and create a project at wiro.ai/panel/project/new to get your API key and secret.

2. Add to Your AI Assistant

Cursor — open MCP settings (Cmd+Shift+P → "Open MCP settings") and add:

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Claude Code:

claude mcp add wiro -- npx -y @wiro-ai/wiro-mcp

Then set environment variables WIRO_API_KEY and WIRO_API_SECRET.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "wiro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Windsurf — add to MCP settings:

{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}

OpenClaw — configure a remote server under mcp.servers:

{
  "mcp": {
    "servers": {
      "wiro": {
        "url": "https://mcp.wiro.ai/v1",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer ${WIRO_MCP_AUTH}"
        }
      }
    }
  }
}

Set WIRO_MCP_AUTH in OpenClaw's environment, then verify with
openclaw mcp doctor wiro --probe. On older OpenClaw releases without that
probe command, use openclaw mcp show wiro, restart OpenClaw, and run
/tools verbose.

Hermes — add to ~/.hermes/config.yaml:

mcp_servers:
  wiro:
    url: "https://mcp.wiro.ai/v1"
    headers:
      Authorization: "Bearer ${WIRO_MCP_AUTH}"
    timeout: 60
    connect_timeout: 10

Store WIRO_MCP_AUTH in ~/.hermes/.env, then run /reload-mcp and /tools.

3. Start Using

Ask your AI assistant:

• "Generate a photorealistic image of a mountain lake at sunset"
• "What video generation models are available on Wiro?"
• "Show me the parameters for openai/sora-2"
• "Create a 5-second video with Kling V3 — a drone shot over mountains"
• "Check the status of my last task"
• "Show my latest productions and open the newest result"

Authentication

Wiro supports two authentication types (chosen when creating a project):

Signature-Based (Recommended)

More secure. Requires both API key and API secret.

WIRO_API_KEY=your-api-key
WIRO_API_SECRET=your-api-secret

API Key Only

Simpler. Only requires the API key. Omit WIRO_API_SECRET from your config.

WIRO_API_KEY=your-api-key

Available Tools

For long generations, run_model returns the existing task ID and token when its
wait budget expires. The assistant must continue with wait_for_task; retrying
run_model creates a separate billable task.

LLM-friendly responses

All tools publish typed MCP input and output schemas. Successful calls return
structuredContent for reliable chaining, concise text content for clients
that only render text, and MCP resource links for generated media.
Model parameters remain catalog-driven: json and json-array fields are sent
as structured values in the same run_model.params object as all other inputs.
Use get_model_schema as the source of truth for continuation fields.
previousTaskToken is the single continuation reference. Send it with exactly
one new prompt or non-empty messages value for a stateful next turn, or with
toolOutputs for a tool-result continuation.

LLM task outputs preserve the public Task Detail segment names and casing:
thinking, answer, function_call, and custom_tool_call, including
call_id, finishreason, and optional normalized token usage.
Only validated fields are projected into structured MCP output. When segments
are present, response is derived from ordered answer segments instead of
raw debug transport; tasks without a typed projection retain their normal
debugoutput response.

Completed tool calls return a continuation template in the existing
nextAction. Execute each call, replace the output placeholders, and pass the
same ordinary run_model.params object back:

{
  "tool": "run_model",
  "arguments": {
    "model": "owner/model",
    "params": {
      "previousTaskToken": "task-token",
      "toolOutputs": [
        {
          "call_id": "call_01",
          "output": "<tool result>"
        }
      ]
    }
  }
}

Function calls carry JSON-string arguments; custom tool calls carry free-form
input. Tool results are request values in toolOutputs, not response
segments.

Completed media responses also include an assistant-audience delivery
instruction. Some MCP clients expose a resource_link as tool metadata instead
of previewing it inside the tool card, so the assistant is explicitly told to
render images and preserve clickable media links in its user-facing response.
The standard resource link and full-resolution URL remain available to every
client; no base64 media payload is required.

Task responses use the stable states submitted, running, completed,
failed, and cancelled. When more work is required, the response includes an
executable nextAction:

{
  "state": "running",
  "task": {
    "id": "123",
    "token": "task-token",
    "status": "task_start"
  },
  "outputs": [],
  "nextAction": {
    "tool": "wait_for_task",
    "arguments": { "tasktoken": "task-token" },
    "reason": "Continue this exact task. Do not call run_model again."
  }
}

Generation chain:
search_models → get_model_schema → run_model → wait_for_task

Cross-conversation history:
list_tasks → get_task

Hosted MCP Server

Wiro also provides a hosted MCP server at https://mcp.wiro.ai/v1 that requires no local installation. See the MCP Server documentation for setup instructions.

Documentation

• MCP Server (Hosted) — setup guides for Cursor, Claude Code, Claude Desktop, Windsurf, OpenClaw, and Hermes
• Self-Hosted MCP — run locally with npx, environment variables, library usage
• Authentication — signature-based vs API Key Only
• Run a Model — how the Run endpoint works
• Tasks — task lifecycle, statuses, determining success
• Concurrency Limits — concurrent task limits based on balance
• Error Reference — error codes and handling

Using as a Library

This package exports its core components for use in custom MCP servers:

import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { createMcpServer } from '@wiro-ai/wiro-mcp/server';

const client = new WiroClient('your-api-key', 'your-api-secret');
const server = createMcpServer(client);

Exports

// Import specific components
import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { registerTools } from '@wiro-ai/wiro-mcp/tools';

Environment Variables

Links

• Wiro AI
• Dashboard
• Models
• API Documentation
• Create Project

License

MIT — see LICENSE for details.