Wiro MCP README

Wiro MCP Server

Official MCP server for Wiro AI: run image, video, audio and LLM models, build and run workflows, and deploy and talk to AI agents from Cursor, Claude Code, Claude Desktop, Windsurf and any other MCP client.

Website · Models · Docs · Dashboard

@wiro-ai/wiro-mcp is a TypeScript Model Context Protocol server that runs locally over stdio with npx. Its tools are grouped in three sets:

• Models: search the Wiro AI model catalog, read a model's parameters and price, run it and wait for the result, upload input files and browse past tasks.
• Workflows: build multi-step workflows that chain models, run them, resume failed runs, browse the public gallery, and design workflows together with the Workflow Agent.
• Agents: talk to Studio, the creative agent that runs models for you, and deploy, configure, run and message your own agents built from templates or from scratch.

Playbooks explain each job step by step, so the assistant knows the order of calls, what costs money and what needs your approval. The hosted server at https://mcp.wiro.ai/v1 serves the same tools with nothing to install.

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 to your API key, or to API_KEY:API_SECRET for a project with signature-based auth. 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 (your API key, or API_KEY:API_SECRET) in ~/.hermes/.env, then run /reload-mcp and /tools.

3. Start Using

Ask your AI assistant:

Models

• "Generate a photorealistic image of a mountain lake at sunset"
• "What video generation models are available on Wiro?"
• "Show me the parameters for google/veo3-1"
• "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"

Workflows

• "Build a workflow that turns a product photo into a short ad video, then run it on this photo"
• "Find a public workflow for podcast covers and run it with my show's name"
• "Ask the Workflow Agent to add an upscale step to my product ad workflow and save it"
• "Why did my last workflow run fail? Resume it if it can be resumed"

Agents

• "Ask Studio for three logo ideas for a coffee shop"
• "Which agent templates can manage Instagram? What does each plan cost?"
• "Deploy the Instagram manager agent on the Starter plan and tell me what it still needs"
• "Tell my support agent to summarise today's tickets"

Authentication

Wiro AI supports two authentication types, chosen when you create 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

The hosted server takes the same credentials as a bearer token: Authorization: Bearer API_KEY:API_SECRET for a signature-based project, or Authorization: Bearer API_KEY for an API Key Only project.

Available Tools

Models

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.

Workflows

A workflow chains models and built-in utility steps into one graph with its own inputs and outputs. Every model step is charged like a normal model run when it finishes. Wiro fills a model input you leave out with the model's default, so the save result lists what it filled, and a graph can be at most 40 KB of JSON.

The Workflow Agent designs workflows with you in plain language: talk to it with send_agent_message and agent: "workflow-agent", attach an existing workflow to edit, then save its proposal with save_workflow_from_agent. Conversations started through this server belong to the connected project and are separate from your Workflow Agent chats on wiro.ai.

Agents

Talk to any Wiro agent with one set of tools. agent is "studio", "workflow-agent" or the id of one of your own agents. Session names use letters, digits, dots, dashes, underscores and colons, up to 128 characters (100 for the Workflow Agent), and cannot end in "-r" followed by a number. Studio refuses a message under any other name; a session it has under another name can be read and deleted, and to go on with it you start a new session.

Studio is Wiro's creative agent: it picks and runs models for you and charges your wallet after each reply. Your own agents run on a monthly plan with credits.

Account and guides

The server also offers prompts for common jobs (build_workflow, deploy_agent, create_with_studio, talk_to_my_agent). In clients that support MCP prompts they appear as ready-made commands.

Choosing tool groups

All groups are on by default. Some clients work best with fewer tools; set WIRO_TOOLSETS to a comma-separated list of models, workflows and agents to load only those. get_account, get_playbook and search_docs are always available, and workflows also brings the model search tools it needs. The conversation tools for Studio and the Workflow Agent, with save_workflow_from_agent, come with either workflows or agents, and each prompt appears only when its tools are loaded. If a job needs a tool from a group that is not loaded, the server instructions tell the assistant to say so.

"env": {
  "WIRO_API_KEY": "your-api-key",
  "WIRO_TOOLSETS": "models,workflows"
}

Paid and irreversible actions

Running a model or workflow, sending a message to Studio or the Workflow Agent, and messages to your own agents (which use the agent's credits) cost money. Agent plans, plan changes, credit packs and skill changes are charged to your wallet, so those tools first return the price (for a change inside a billing period, the amount Wiro works out for the time left) and only act when called again with confirm: true and the quote's reference (confirm_charge_usd with the approved amount, or the quote's idempotency_key for skill changes) after you agree. If the price changed in between, nothing is charged and you get a new quote. Deleting a workflow, an agent, a conversation or an account connection also waits for confirm: true, and so do connecting an agent to a Wiro project with bind_agent_project and replacing a workflow's steps with update_workflow or save_workflow_from_agent: you see a summary of the change first, with the old and new value of each step input that changes. No tool adds funds or takes a card payment: funds are added in the Wiro dashboard, and an agent plan paid by card is upgraded or topped up there. The connected project decides the workspace: a personal project uses your personal wallet, a team project uses the team wallet.

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. Every tool that takes arguments refuses an argument it does not know and names the right one where it can, such as taskid for task_id. The one exception is a call that carries toolCallId, a key some clients add on their own: it reads only the arguments the tool takes. 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. A model can continue a conversation only when its schema lists session_id: send the same session_id on every turn, the first one included, with the next prompt. A turn that ended with tool calls is continued with previousTaskToken, that turn's task token, and toolOutputs, as the turn's nextAction template shows.

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>"
        }
      ],
      "session_id": "launch-taglines"
    }
  }
}

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. Only files on Wiro's own hosts are returned this way. Other links in an agent's reply stay plain links in the text, without the delivery instruction.

In the text of a result, an agent's reply, the file and link addresses taken from it and a model's answer sit in fenced blocks under fixed labels, and the server's own guidance (**Next:** lines and notes) stays outside them, so an assistant can treat that text as content and act only on that guidance and nextAction. structuredContent keeps the text unchanged in its own fields. A workflow run's text outputs and step errors show the same way, each under a fixed label. A saved workflow's title, description and input list are shown as data too, in every result, since an agent or another person can have written them.

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

Workflow chain: search_models → get_model_schema → create_workflow → run_workflow → wait_for_workflow_run

Workflow Agent chain: send_agent_message (agent "workflow-agent") → get_agent_message → save_workflow_from_agent → run_workflow

Agent chain: list_agent_templates → get_agent_template → deploy_agent → set_agent_credentials / connect_agent_oauth / bind_agent_project → control_agent → send_agent_message

Hosted MCP Server

Wiro AI also hosts the same tools at https://mcp.wiro.ai/v1 over streamable HTTP, so nothing has to be installed locally. Send your credentials in the Authorization header as shown under Authentication. The MCP Server documentation has setup instructions for each client.

Install as a plugin

wiroai/Wiro-Plugin packages the hosted server as a plugin for Cursor, Claude Code, Gemini CLI and Devin. Its README has the install command for each of them.

Documentation

• MCP Server (Hosted): setup guides for Cursor, Claude Code, Claude Desktop, Windsurf, Gemini CLI, Devin, OpenClaw, and Hermes
• Self-Hosted MCP: run locally with npx, environment variables, library usage
• Node.js Library: use WiroClient from this package in your own Node.js or TypeScript code
• 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
• Agents Overview: templates, plans, credits and the agent lifecycle
• Agent Builder: build an agent from skills instead of a template
• Agent Skills and Agent Credentials: what each skill needs and how accounts are connected
• Agent Messaging: conversations, sessions and replies

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);

If a project uses signature-based auth and no API secret was given, tool errors say that the secret is missing. When your server takes credentials in its own way, tell users where the secret goes:

const client = new WiroClient(apiKey, apiSecret, undefined, {
  missingSecretHint: 'This project uses signature-based auth. Enter API_KEY:API_SECRET as the API key.',
});

To send headers of your own with every API request, pass requestHeaders: a function that gets one object, { pathname, apiKey }, for each request (pathname such as /v1/Tool/List) and returns a plain object of string values. The headers it returns are sent after the client's own. If they include x-api-key, x-signature, x-nonce or Content-Type, in any letter case, the request fails before it is sent.

Exports

// Import specific components
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { createMcpServer } from '@wiro-ai/wiro-mcp/server';
import { registerTools } from '@wiro-ai/wiro-mcp/tools';

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

// Only the model and workflow tools
const server = createMcpServer(client, { toolsets: ['models', 'workflows'] });

// Or add the model tools to an McpServer you already have
const myServer = new McpServer({ name: 'my-server', version: '1.0.0' });
registerTools(myServer, client, { toolsets: ['models'] });

Environment Variables

More from Wiro AI

Website · Models · Docs · X

License

MIT, see LICENSE.