Connect your agent

Willo runs an MCP server for your business. Your coding agent connects to it with a token, then reads and changes the business through the same rules Willo's own chat follows. Setup takes three steps.

1. Create a token

An owner or admin of the business does this once per agent. Agent tokens come with the Builder plan and up; on a plan below that, the card offers an upgrade instead. See Pricing.

1. Open your business in Willo and go to Settings → AI Agents.
2. On the AI agents card, choose Create a token (or New token if the business has some already).
3. Give it a name you will recognise later, such as "Claude Code on my laptop".
4. Pick what it may do. Read-only lets the agent read the site's code, the backend and the business. Read + act also lets it make changes, with anything risky stopping for your approval.
5. Pick how long it lasts: 30, 90 or 365 days. 90 is the default.

The token is shown once. Copy it now; Willo keeps only a hash and cannot show it again. If you lose it, revoke it and create another. Agent tokens explains scopes and expiry in full.

2. Add Willo to your agent

The server address is https://api.willo.ai/mcp. Each setup below keeps the token out of config files: the file names an environment variable, and you set the variable in your shell. That way a config file can be committed to git without leaking the token.

claude mcp add --transport http --scope project willo https://api.willo.ai/mcp --header 'Authorization: Bearer ${WILLO_AGENT_TOKEN}'

export WILLO_AGENT_TOKEN="willo_agt_…"

{
  "mcpServers": {
    "willo": {
      "url": "https://api.willo.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:WILLO_AGENT_TOKEN}" }
    }
  }
}

export WILLO_AGENT_TOKEN="willo_agt_…"

[mcp_servers.willo]
url = "https://api.willo.ai/mcp"
bearer_token_env_var = "WILLO_AGENT_TOKEN"

export WILLO_AGENT_TOKEN="willo_agt_…"

The dashboard card shows the same steps with your real token filled in, right after you create it.

3. Make your first three calls

Ask your agent something like: "Using the willo tools, check the business's status, list the site's files and summarise the business." It should call:

1. willo_status: where the business stands. Whether a draft is open, the live site's last deploy and the draft preview's last build. Call it first, because it tells the agent whether its reads see the draft or the live site.
2. willo_list_files: the site's code, from the draft branch when one exists, otherwise from what is live.
3. willo_business: the business as Willo tracks it. Current phase, active goals and today's activity.

All three are free and read-only. If they work, you are connected. Next, try your first change.

Clients that need OAuth

Willo's server authenticates with a bearer token. Claude Desktop and ChatGPT on the web connect to remote servers only through an OAuth sign-in, so they can't connect to it. ChatGPT users can connect through Codex CLI.

When it doesn't connect

• 401 Unauthorized. The token is missing, mistyped, expired or revoked. Check the variable is set in the shell that started the agent, then check the token's row on Settings → AI Agents.
• 403 with plan_required or plan_lapsed. The business is on a plan below Builder, or its plan has lapsed. The token isn't revoked: it works again once an owner or admin upgrades on the Billing page. Error codes lists every refusal.
• The agent doesn't see a tool. A read-only token sees only the read tools. Create a read + act token for changes.
• An old copy keeps being used. If you once ran a claude mcp add command with the token pasted in, remove that saved copy with claude mcp remove willo -s local.