Wiro MCP Server

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools directly. With the Wiro MCP server, your AI assistant can find and run models, build and run workflows, create media with Studio, and deploy and talk to your own agents, all without leaving your editor or chat app.

The hosted MCP server is available at mcp.wiro.ai/v1. Most apps connect with the browser sign-in above. Clients that send custom request headers, including Cursor, Claude Code, Windsurf, Kiro, goose, OpenClaw, and Hermes, can use your API key instead. An API key sent in a header is never stored on the hosted server.

You need a Wiro account. With a browser sign-in you pick a project while connecting. For the API key method, create a project here.

Links

• Model Context Protocol (MCP): open standard specification
• GitHub: wiroai/Wiro-MCP (source code & self-hosting instructions)
• npm: @wiro-ai/wiro-mcp (npm package)
• Wiro Model Catalog: browse all available models
• Create API Key: get started in seconds

Browser sign-in details

ChatGPT, Claude (claude.ai, Claude Desktop and Claude Code), Cursor, VS Code, Gemini CLI, Codex, Zed, Devin, Kiro, goose, Grok, Grok Bot, Cline and MCP Inspector connect this way, and so does any app on your computer that follows the MCP authorization spec. An app that signs in through its own website needs its callback address on Wiro's list: write to [email protected] to add one.

Projects and billing

• Each connection uses one project. A personal project bills your personal wallet, a team project the team's wallet.
• In a team, members can connect the projects they created. Team admins and the organization owner can connect any project of the team.
• A project with an IP whitelist only accepts calls from the addresses on it. ChatGPT and Claude call from their own servers, so pick a project open to all addresses for them. Apps on your computer, such as Claude Code, Cursor and VS Code, call from your own address.

How long it stays connected

You pick it on the sign-in page: 7 days, 30 days, 90 days (the default), 180 days, 1 year, or unlimited. When the time is up, the app asks you to sign in again. An unlimited connection lasts until you disconnect it.

A connection also ends when its project is removed, or when you leave the team or lose the role that allowed it. The same happens once the project's API key stops working, for example when the person who created a team project leaves the team; the sign-in page then no longer offers that project. Access tokens last one hour and renew on their own, so there is nothing to copy or rotate.

See, change and disconnect apps

Every app you connected is listed under Projects, Connected Apps in the panel, with its project, when it was last used and when it ends. Pick a new length there to extend or shorten it; it counts from that day. Disconnect ends its access within a minute, and the app asks you to sign in again the next time.

For MCP client developers

Use the authorization code flow with PKCE (S256). Authorization responses carry iss. Sign-in returns only to the callbacks of known apps and to loopback addresses on your own computer (any port). To add your app's callback, write to [email protected].

Setup

Connect your AI assistant to Wiro's MCP server. Pick your client:

{
  "mcpServers": {
    "wiro": {
      "url": "https://mcp.wiro.ai/v1"
    }
  }
}

claude mcp add --transport http wiro https://mcp.wiro.ai/v1

/plugin marketplace add wiroai/Wiro-Plugin
/plugin install wiro-ai@wiro

claude mcp add --transport http wiro \
  https://mcp.wiro.ai/v1 \
  --header "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"

{
  "mcpServers": {
    "wiro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp@1.5.0"],
      "env": {
        "WIRO_API_KEY": "YOUR_API_KEY",
        "WIRO_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

{
  "servers": {
    "wiro": {
      "type": "http",
      "url": "https://mcp.wiro.ai/v1"
    }
  }
}

gemini mcp add --transport http wiro https://mcp.wiro.ai/v1

gemini extensions install https://github.com/wiroai/Wiro-Plugin

devin plugins install wiroai/Wiro-Plugin

{
  "mcpServers": {
    "wiro": {
      "url": "https://mcp.wiro.ai/v1"
    }
  }
}

{
  "mcpServers": {
    "wiro": {
      "url": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

extensions:
  wiro:
    name: Wiro AI
    type: streamable_http
    uri: https://mcp.wiro.ai/v1
    headers:
      Authorization: Bearer YOUR_API_KEY
    enabled: true
    timeout: 300

{
  "mcpServers": {
    "wiro": {
      "serverUrl": "https://mcp.wiro.ai/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"
      }
    }
  }
}

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

openclaw mcp doctor wiro --probe

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

https://mcp.wiro.ai/v1

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

Authentication

Apps that support MCP sign-in need no credentials here: see Connect with a browser sign-in. With an API key in the header, the MCP server supports both Wiro authentication types. Your project's auth type determines what credentials you provide.

Signature-Based (Recommended)

More secure. Requires both API key and API secret. Pass them as plain text separated by a colon:

Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET

API Key Only

Simpler. Only requires the API key:

Authorization: Bearer YOUR_API_KEY

No base64 encoding needed. Credentials are sent per-request and are never stored. The server is fully stateless.

Authentication errors

A failed tool call comes back as a normal tool result with isError: true. Its text starts with Wiro API error and the HTTP status, then a message that says what to fix. For example, when a project uses signature-based auth and only its API key was sent:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "## Error\n\nWiro API error 401: This project uses signature-based auth. Enter API_KEY:API_SECRET (the key and secret joined with a colon) as the API key."
  }]
}

Messages you may see while connecting:

A request without an Authorization header never reaches a tool. The MCP endpoint answers HTTP 401 with Missing or invalid Authorization header in the body and a WWW-Authenticate header that points apps to the sign-in. An expired or disconnected sign-in gets the same answer with error="invalid_token", and the app asks you to sign in again. See Error Reference for every Wiro API error.

Available Tools

The MCP server has 50 tools. Most of them belong to one of three groups, Models, Workflows and Agents, and three tools for your account, the playbooks and the docs are always available. Your AI assistant picks the right tool for each request, and for longer jobs it reads a playbook first.

Model slugs: Use the clean/lowercase format owner/model (e.g. openai/sora-2, wiro/virtual-try-on). These correspond to the cleanslugowner/cleanslugproject values returned by search_models.

Models

For long generations, run_model returns the existing task ID and token when its wait ends. The assistant continues with wait_for_task; calling run_model again would start 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 API behind these tools is described on the Workflows page.

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 the MCP server belong to the connected project and are separate from your Workflow Agent chats on wiro.ai. See Workflow Agent.

Agents

One set of tools talks to every Wiro agent. agent is "studio", "workflow-agent" or the guid 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 can't end in -r followed by a number, such as -r2. Studio refuses a message under any other name, and nothing is sent. A Studio session that already has another name can still be read and deleted; to go on with it, start a new session.

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

Account and guides

These three tools are always available, whichever groups are loaded.

Playbooks

A tool description is too short to carry the order of calls, the money rules and the formats of a multi-step job, so the server keeps them in playbooks. The server tells the assistant to read the matching playbook with get_playbook before a multi-step job.

Prompts

The server also offers prompts for common jobs. Clients that support MCP prompts show them as ready-made commands. Each prompt sends the assistant to the matching playbook first.

Paid and irreversible actions

Running a model or a workflow, sending a message to Studio or the Workflow Agent, and messages to your own agents (which use the agent's credits) cost money. The assistant tells you the expected cost in one line before it starts such work.

Agent plans, plan changes, credit packs and skill changes are charged to your wallet, so deploy_agent, manage_agent_billing and apply_agent_skills first return the price (for a change inside a billing period, the amount Wiro works out for the time left). They act only when they are called again with confirm: true and the quote's reference after you agree: confirm_charge_usd with the approved amount, or the quote's idempotency_key for skill changes. 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. get_account shows which one and its balance.

MCP Request and Response Contract

Every tool advertises typed MCP inputSchema and outputSchema values. Successful calls return structuredContent for reliable LLM tool chaining, concise text content for compatibility, and MCP resource links for generated media.

Every tool that takes arguments refuses an argument it does not know, and nothing is run. The answer lists the arguments the tool takes and names the right one where it can, such as taskid for task_id; run_model adds that model parameters go inside params, and run_workflow that input values go inside input. The one exception is a call that carries toolCallId, a key some clients add on their own: the tool then reads only the arguments it takes.

When a task completes with media, Wiro also returns an assistant-audience delivery instruction. MCP clients do not all preview resource_link blocks inside tool cards, so the assistant is explicitly told to render image URLs and preserve clickable video, audio, and file links in its user-facing response. The standard resource link and full-resolution URL remain available without embedding a large base64 payload.

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. The server's own guidance, its Next: lines and notes, stays outside them, so the assistant can treat that text as content and act only on the guidance and nextAction. A workflow run's text outputs and step errors show the same way. 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. structuredContent keeps each text unchanged in its own field.

For example, an LLM submits one generation:

{
  "name": "run_model",
  "arguments": {
    "model": "owner/model",
    "params": { "prompt": "A mountain lake at sunset" },
    "wait": true,
    "timeout_seconds": 45
  }
}

If the generation outlives the bounded wait, the same tool returns the existing task and an executable next action:

{
  "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."
  }
}

Task states are submitted, running, completed, failed, or cancelled. The LLM should execute nextAction when present. A two- or three-minute video can therefore use several bounded wait_for_task calls without creating another billable generation.

Workflow runs, agent replies and agent start-up follow the same pattern: when a wait ends before the job does, the result names the tool and arguments that keep waiting on that same job, such as wait_for_workflow_run or get_agent_message.

An LLM model can continue a chat 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.

Examples

Generate an image

The assistant will use search_models → get_model_schema → run_model and return the image URL.

Generate a video

The assistant will use get_model_schema → run_model, then continue with wait_for_task using the returned token if the generation is still running.

Find models

The assistant will call search_models with categories filter.

Check task status

The assistant will call get_task with the task token from the previous run.

Resume a previous production

The assistant will call list_tasks, select the matching task, and call get_task. History is scoped from the authenticated project; the LLM never sends a user UUID.

Build and run a workflow

The assistant reads the workflows and workflow-graph playbooks, picks a model for each step with search_models and get_model_schema, and saves the graph with create_workflow. It tells you the expected cost, then calls run_workflow and follows wait_for_workflow_run until the video is ready.

Edit a workflow with the Workflow Agent

The assistant finds the workflow with list_workflows and sends your request with send_agent_message (agent: "workflow-agent") with the workflow attached. It shows you the proposal and the models it uses, and saves it with save_workflow_from_agent once you agree to the change.

Fix a failed run

The assistant calls list_workflow_runs with status failed, reads the failed step with wait_for_workflow_run, and continues the run with resume_workflow_run. Steps that already finished are not charged again.

Create with Studio

The assistant checks the balance with get_account, tells you what a Studio turn costs, sends the brief with send_agent_message (agent: "studio") and shows the images from the reply.

Deploy an agent

The assistant compares templates with list_agent_templates and get_agent_template, gets the price from deploy_agent, and deploys only after you confirm the amount. Then it lists the missing setup with get_my_agent and connects the account with connect_agent_oauth. If the agent runs Wiro models, it connects a Wiro project with bind_agent_project once you agree to the project it shows.

Talk to your agent

The assistant finds the agent with list_my_agents, checks that it is running with get_my_agent, and sends the message with send_agent_message. The message uses the agent's credits.

How It Works

The MCP server is stateless. Each request is fully isolated:

1. Your AI assistant sends a request to mcp.wiro.ai/v1 with your credentials
2. The server calls the Wiro API on your behalf
3. Results are returned to your assistant

All tools are dynamic: they fetch model data at runtime. New models are instantly available via MCP.

Tool Reference

The model tools are described one by one below. The workflow, conversation and agent tools follow in tables of their main arguments.

search_models

Search Wiro's model catalog by keyword, category, owner, or any combination. Calls POST /Tool/List on the Wiro API.

Returns a list of models with their cleanslugowner/cleanslugproject (the slug you pass to other tools), title, description, categories, and pricing.

get_model_schema

Get the full parameter schema for a specific model. Calls POST /Tool/Detail on the Wiro API.

Returns the model's parameter groups, each containing items with id, type (text, textarea, select, range, fileinput, etc.), label, required, options, default, and note. Also includes pricing information. Use these to construct the params object for run_model.

recommend_model

Describe what you want to create and get model recommendations ranked by relevance. Calls POST /Tool/List on the Wiro API with relevance sorting.

Returns a list of recommended models with slugs, descriptions, categories, and pricing, sorted by relevance to your task.

explore

Browse curated AI models on Wiro, organized by category. Calls POST /Tool/Explore on the Wiro API. No parameters required.

Returns models grouped into curated sections like "Recently Added", "Image Generation", "Video", etc. Each model includes its slug, description, categories, and rating. Use this to discover what's available without searching.

run_model

Run any AI model on Wiro. Calls POST /Run/{owner}/{model} on the Wiro API.

When wait=true, returns the final task result including pexit (exit code, "0" = success), clickable outputs, and debugoutput (LLM text responses).

If the wait budget expires, the tool returns a normal Task Still Running result with taskid, tasktoken, and the last status. The generation continues. Call wait_for_task; do not call run_model again, because that creates a second billable task.

When wait=false, returns taskid and tasktoken immediately. Use wait_for_task to wait or get_task for a one-time status check.

wait_for_task

Wait for an existing task without submitting another model run. Calls POST /Task/Detail repeatedly for a bounded interval.

If the task completes, this tool returns the final text and file outputs. If it is still active, call wait_for_task again with the same identifier. This does not create or bill another model run.

get_task

Check task status and get results. It performs one immediate check by default, or a short bounded wait when wait_seconds is set. Calls POST /Task/Detail on the Wiro API.

Returns the task's current status, pexit (process exit code), outputs (file URLs), debugoutput (LLM responses), elapsedseconds, and totalcost.

Determining success: Check pexit, where "0" means success and any other value means failure. For LLM models, the response is available as structured content in outputs (with contenttype: "raw") and as merged text in debugoutput. See Tasks for the full task lifecycle.

A live WebSocket task_error event is an interim stderr log, while persisted status: "task_error" returned by Task/Detail marks a pre-execution recovery state. Neither closes the task; wait_for_task continues until task_postprocess_end or task_cancel.

list_tasks

List recent model-generation tasks owned by the authenticated project. Calls POST /Task/List without a uuid; Wiro derives the owner from the API credential.

Returns newest-first task summaries with stable state, model, task ID, timestamps, duration, cost, and limited output links. Call get_task with a returned taskid for the complete result.

get_task_price

Get the cost of a completed task. Calls POST /Task/Detail on the Wiro API and returns billing information.

Returns the task's billing status, total cost, and duration. Only successful tasks (pexit: "0") are billed. Failed tasks show $0 with a clear explanation that they were not charged.

cancel_task

Cancel a task that is still queued (before worker assignment). Calls POST /Task/Cancel on the Wiro API.

Tasks that have already been assigned to a worker cannot be cancelled. Use kill_task instead.

kill_task

Kill a task that is currently running (after worker assignment). Calls POST /Task/Kill on the Wiro API.

The worker will stop processing and the task will move to task_cancel status.

upload_file

Upload a file from a URL to Wiro for use as model input. Downloads the file and uploads it via POST /File/Upload.

Returns the uploaded file's Wiro URL, which can be passed to any model parameter that accepts a file.

search_docs

Search the Wiro documentation for guides, API references, and code examples.

Returns relevant documentation sections matching your query.

get_account and get_playbook

get_account names the workspace of the connected project, personal or a team, and shows that wallet's balance. It is also the call that proves the connection works, since model search, schema reads and search_docs answer without credentials. Without arguments it reads only the balance. With recent_transactions (1 to 50) it also lists that many of the wallet's latest transactions, newest first, as the Transactions page of the Wiro dashboard shows them: each row's time, type, whether it adds to the wallet or takes from it, the amount in USD and what it was for, such as a model run, a store item or an agent. That is how to check that a charge or a credit landed. In a team the wallet is shared, so the list holds the whole team's activity. transactions_start pages back: pass the nextStart of the last answer. get_playbook takes topics, one or more of the playbook topics listed under Available Tools, such as ["workflows"] or ["agents", "billing"].

Workflow tools

The workflow, conversation and agent tools publish their full input schemas, which your MCP client reads, so the tables below list only their main arguments. A workflow is named by its full slug, such as product-shots-a1B2c, and a run by its run token. The Workflows page describes the API behind these tools.

Conversation tools

These tools work the same for Studio, the Workflow Agent and your own agents. agent is "studio", "workflow-agent" or the guid of one of your agents, and session names the conversation, following the session name rule under Available Tools. See Studio, Workflow Agent and Agent Messaging.

Agent tools

An agent is named by its guid, which list_my_agents returns. See Agent Overview, Agent Builder, Agent Credentials & OAuth and Agent Skills for the API behind these tools.

list_projects lists the projects of the connected project's workspace by id and name. It marks the connection's own project, the projects this connection can connect to an agent (the ones you created, or any project of a team you are an admin of) and the projects with an IP whitelist, and it shows no keys. bind_agent_project connects the Wiro project an agent runs models with. Called without confirm, it changes nothing: it shows the project, the one it replaces, whether a running agent restarts and which wallet pays for the agent's model runs (the wallet of the workspace that owns the project). After you agree, the assistant repeats the call with confirm: true, as its nextAction shows. Connecting the project an agent already has changes nothing and restarts nothing. On a team agent, a team admin can connect any project of the team, and the person who deployed the agent the projects they created. The API behind it is POST /UserAgent/CredentialProjectBind.

FAQ

What models can I use?

All models in the Wiro catalog.

Is my API key stored?

No. The server is fully stateless. Credentials are sent per-request and never stored or logged.

Does it cost extra?

No. The MCP server itself is free. You pay the normal prices for the work the tools start: model runs, the model steps of workflow runs, Studio and Workflow Agent turns, and agent plans and credits.

What about rate limits?

The hosted MCP endpoint counts requests for each Bearer token, or for each caller IP when a request has none, in a fixed 60-second window. Each window allows 60 tool calls and prompt reads, where every message of a batch counts, and 300 other requests, such as initialize, notifications, listings and ping. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the 60-call budget.

A request over the limit gets HTTP 429 with Retry-After, the same RateLimit headers for the limit it hit, and a JSON-RPC error (code -32000) that says it was not run and when to try again. A batch larger than one window allows gets HTTP 400 (code -32600): it was not run, and it has to be split. These limits come on top of Wiro API project limits. Long generations do not require rapid polling: follow the returned bounded wait_for_task action.

Can I self-host?

Yes. See Self-Hosted MCP for instructions.