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 or Docker. 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 and the Docker image do 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-mcpThen 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: 10Store 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"
Docker
Every release is also published on Docker Hub as
wiroai/wiro-mcp, for
linux/amd64 and linux/arm64. The image runs the same stdio server, so you
need Docker but not Node.js:
docker run -i --rm -e WIRO_API_KEY wiroai/wiro-mcp-e WIRO_API_KEY hands the variable from your environment to the container.
For a project with signature-based auth, add -e WIRO_API_SECRET as well.
WIRO_TOOLSETS passes through the same way. Keep -i, since the server reads
its requests from stdin, and leave out -t.
In a client config, docker is the command and the credentials go in env.
This works in Cursor, Claude Desktop and Windsurf:
{
"mcpServers": {
"wiro": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "WIRO_API_KEY", "-e", "WIRO_API_SECRET", "wiroai/wiro-mcp"],
"env": {
"WIRO_API_KEY": "your-api-key",
"WIRO_API_SECRET": "your-api-secret"
}
}
}
}Claude Code:
claude mcp add wiro -e WIRO_API_KEY=your-api-key -e WIRO_API_SECRET=your-api-secret -- docker run -i --rm -e WIRO_API_KEY -e WIRO_API_SECRET wiroai/wiro-mcpFor an API Key Only project, leave out the WIRO_API_SECRET value. Docker only
passes variables that are set, so the -e WIRO_API_SECRET argument can stay.
Image tags follow the npm versions: wiroai/wiro-mcp:<version> pins a release
and latest is the newest one. A client does not fetch a newer latest by
itself, so run docker pull wiroai/wiro-mcp to update. Pulling once before the
first start also means the client does not wait for the download.
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
| Tool | Description |
|---|---|
search_models |
Search and browse AI models by keyword, category, or owner |
get_model_schema |
Get full parameter schema and pricing for any model, or the parameters and output ports of a workflow utility |
recommend_model |
Find models for a goal from two or three key words, best matches first |
explore |
Browse curated models grouped by category, no parameters needed |
run_model |
Run any model, waiting up to 45s by default (up to an hour with timeout_seconds) before it returns a recoverable task token |
wait_for_task |
Continue waiting for an existing task without submitting or billing a duplicate run |
get_task |
Check task status immediately or wait up to 45s with wait_seconds |
list_tasks |
Browse authenticated task history across conversations, then continue with get_task |
get_task_price |
Get the cost of a completed task |
cancel_task |
Cancel a queued task |
kill_task |
Stop a queued or running task |
upload_file |
Upload a file from a public http(s) URL (up to about 100 MB) for use as model input |
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.
| Tool | Description |
|---|---|
list_workflows |
List the workflows in your workspace, or search the public gallery by text, tag or model |
get_workflow |
Read a workflow's inputs, outputs and step graph |
create_workflow |
Save a new workflow from a step graph. Wiro checks it against the live model catalog and returns every problem it finds at once |
update_workflow |
Edit a workflow's title, description, tags or graph without overwriting newer changes; a new graph is saved only after you confirm a summary of the change |
clone_workflow |
Copy a public workflow into your workspace |
delete_workflow |
Delete a workflow, after your confirmation |
run_workflow |
Run a workflow and wait for its outputs; can stop after a chosen step to test the first steps |
wait_for_workflow_run |
Keep waiting on a run, read its outputs, or see why a step failed |
resume_workflow_run |
Continue a failed or stopped run without paying again for finished steps |
list_workflow_runs |
Browse past and current runs, including runs started on wiro.ai |
save_workflow_from_agent |
Save a workflow the Workflow Agent proposed, as a new workflow, or onto an existing one after you confirm a summary of the change |
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.
| Tool | Description |
|---|---|
send_agent_message |
Send a message and wait for the reply, with any media, workflows or model runs it produced |
get_agent_message |
Keep waiting on a reply, or read one again |
get_agent_conversation |
List conversations, or read one conversation's history |
cancel_agent_message |
Stop a reply that is still being written |
delete_agent_session |
Delete a conversation and the agent's memory of it, after your confirmation |
list_studio_results |
List the images, videos and other results Studio generated for you |
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.
| Tool | Description |
|---|---|
list_agent_templates |
Browse ready-made agent templates and the three monthly plans |
get_agent_template |
Read a template's skills, plans, and the accounts and keys it needs |
list_agent_skills |
Browse the skills an agent can have, and what each one needs to work |
deploy_agent |
Deploy an agent from a template or build one from skills, on the Starter, Pro or Max plan; shows the plan's price, the wallet it charges and the other plans' prices, and asks before charging |
list_my_agents |
List your agents with their status, plan and credits |
get_my_agent |
Read one agent's setup, plan and credits; can wait until it is running |
control_agent |
Start, stop or restart an agent |
update_agent |
Change an agent's name, description, time zone, models, chat commands and setup from chat |
apply_agent_skills |
Turn skills on or off; every plan includes every skill, so a change costs nothing |
set_agent_credentials |
Save the keys, tokens and settings an agent's skills and channels need, such as a Telegram bot token or a Gmail app password |
connect_agent_oauth |
Connect sign-in accounts such as HubSpot or X for the services an agent's skills use; you approve the connection in your browser. Some services need your own app keys or a token first |
disconnect_agent_oauth |
Disconnect a connected account, after your confirmation |
list_projects |
List the projects of the connected project's workspace, to pick one for an agent; no keys are shown |
bind_agent_project |
Connect an agent to a Wiro project so it can run models, with no key in the chat; shows the project first, then asks for your confirmation |
manage_agent_custom_skill |
Add, edit, schedule, restore or remove an agent's own instructions and scheduled tasks; turning off its approval policy or changing its rules needs your confirmation |
manage_agent_billing |
Subscribe, move to another plan, cancel, renew or buy extra credits from your wallet, after your confirmation |
get_agent_activity |
Read an agent's credit usage and activity logs, including who changed what on it |
delete_agent |
Delete an agent, after your confirmation |
Account and guides
| Tool | Description |
|---|---|
get_account |
Show which workspace the connected project belongs to, its wallet balance and, when you ask, the wallet's recent transactions |
get_playbook |
Step-by-step guides: getting started, models, workflows, workflow graphs, the Workflow Agent, Studio, agents and billing |
search_docs |
Search the Wiro documentation for guides and API references |
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, moves to a larger plan and credit packs are charged to your wallet, so
those tools first return the price (for a move inside a billing period, the
amount Wiro works out for the time left) and only act when called again with
confirm: true and confirm_charge_usd, the approved amount, after you agree.
If the price changed in between, nothing is charged and you get a new quote.
Turning an agent's skills on or off costs nothing, since every plan includes
every skill. A move to a smaller plan starts with the next renewal, with
nothing charged or refunded, and waits for confirm: true too. 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 moves to a larger plan or is 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
WiroClientfrom 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
| Export | Description |
|---|---|
createMcpServer(client, options?) |
Creates an McpServer with the tools, prompts and server instructions registered. options.toolsets picks tool groups and the prompts that use them; options.instructions replaces the instructions; options.wrapTool(tool, handler) returns the handler to register for each tool, for your own logging or permission checks; options.maxToolInputElements caps the array elements and object members one tool call may carry (default 10000, Infinity turns the check off) |
WiroClient |
API client with both auth types; post(path, body) calls any Wiro API endpoint with the same credentials, and isOwnApiKey(value) says whether a value is this client's key |
registerTools(server, client, options?) |
Registers the tools on an McpServer you already have, with the same toolsets and wrapTool options. That server then lists every tool schema, its own tools included, as JSON Schema 2020-12 |
advertiseJsonSchema2020_12(server) |
Makes an McpServer list its tool schemas as JSON Schema 2020-12. Call it when you register single tools from @wiro-ai/wiro-mcp/tools instead of using registerTools |
withJsonSchema2020_12(transport) |
The same for one transport: await server.connect(withJsonSchema2020_12(transport)) |
parseToolsets(value) |
Parse a WIRO_TOOLSETS-style list such as "models,agents" |
// 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
| Variable | Required | Description |
|---|---|---|
WIRO_API_KEY |
Yes | Your Wiro project API key |
WIRO_API_SECRET |
No | Your Wiro project API secret (for signature auth) |
WIRO_API_BASE_URL |
No | Override API base URL (default: https://api.wiro.ai/v1) |
WIRO_TOOLSETS |
No | Comma-separated tool groups to load: models, workflows, agents (default: all) |
More from Wiro AI
| Repository | What it is |
|---|---|
| Wiro-Plugin | Wiro AI plugin for Cursor, Claude Code, Gemini CLI, Devin, Antigravity and Kiro |
| Wiro-Skills | Agent skills for images, image edits, video, music, speech, transcripts, 3D and model search |
| Wiro-LLM | Vercel AI SDK provider for chat, images, speech, transcription and video, @wiro-ai/wiro-llm on npm |
| Wiro-Chromium-Extension | Wiro AI extension for Chrome, Edge, Opera and Brave |
| Wiro-Firefox-Extension | Wiro AI add-on for Firefox |
| Wiro-Safari-Extension | Wiro AI extension for Safari on the Mac |
| Swift-QuickStart | WiroKit, the Wiro AI SDK for iOS |
| Kotlin-QuickStart | WiroKit, the Wiro AI SDK for Android |
| Dart-QuickStart | Wiro AI SDK for Dart and Flutter, wiro on pub.dev |
| ReactNative-QuickStart | Wiro AI SDK for React Native and Expo, @wiro-ai/wiro-react-native on npm |
| Swift-Realtime | Realtime voice AI example for iOS |
| Kotlin-Realtime | Realtime voice AI example for Android |
| Dart-Realtime | Realtime voice AI example for Flutter |
| ReactNative-Realtime | Realtime voice AI example for React Native |
| n8n-nodes-wiro | One Wiro AI node for n8n with a searchable model picker, @wiro-ai/n8n-nodes-wiro on npm |
| Wiro-Dify-Plugin | Wiro AI plugins for Dify: the LLM gateway as a model provider, plus image, video, speech and music tools |
| Wiro-ComfyUI | Wiro AI nodes for ComfyUI |
| Wiro-Hermes | Wiro AI plugins for Hermes Agent: image, video, audio and 3D tools, plus the LLM gateway as a model provider |
| Wiro-Zed | Wiro AI MCP server extension for Zed |
| Wiro-Action | GitHub Action for Wiro AI models and the LLM gateway, on the GitHub Marketplace |
| Wiro-Raycast | Wiro AI extension for Raycast: image and video generation, LLM chat and model search |
| Wiro-WordPress | Wiro AI plugin for WordPress: featured images, image edits, alt text, narration and SEO suggestions |
| Wiro-Obsidian | Wiro AI plugin for Obsidian: images, video, speech, music, transcription and text tools |
| Wiro-Blender | Wiro AI add-on for Blender: text to 3D, image to 3D and textures |
| Wiro-Figma | Wiro AI plugin for Figma: images, vectors, image edits and text |
| Wiro-Next-Starter | Next.js starter for Wiro AI: Playground, image, video and audio tools, and LLM chat, ready for Vercel and Railway |
| Wiro-Docs | Source of the Wiro AI API docs |
| wiroai.github.io | Every open-source project from Wiro AI on one page, with a page for each repository |
License
MIT, see LICENSE.