> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegoro.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# For AI agents: MCP
> Add Goro to Claude, Cursor or any MCP client as a connector, and your agent gets the whole catalog as six tools.
Goro runs a remote MCP server. Add one URL to your client and the agent gets
six tools that reach the entire catalog, on the same balance and the same
prices as the HTTP API.
```
https://mcp.usegoro.ai/mcp
```
## 1. Add the connector
In Claude, Cursor, or any MCP client that supports remote servers, add a
custom connector with the URL above. The client handles the rest: it registers
itself, opens Goro's consent screen in a browser, and stores the token it gets
back.
Transport is Streamable HTTP. The server is stateless per request, so there is
no session to keep alive and nothing to reconnect.
## 2. Authorise it
The consent screen asks for a Goro API key, the `goro_live_` one from
[app.usegoro.ai](https://app.usegoro.ai). That key identifies which workspace
and balance the connector will spend from. Paste it once, approve, and the
client is connected.
Two scopes exist, and a client that does not ask for a narrower grant gets
both:
| Scope | Grants |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `tools:read` | `discover_tools`, `inspect_tool`, `create_upload`, `get_run`, `wallet_balance`, `remember_tool_choice`, `forget_tool_choice` |
| `tools:run` | `run_tool` |
Access tokens last an hour and the client refreshes them silently. Refresh
tokens last 30 days and rotate on every use.
Building the client yourself rather than using an existing one? The OAuth
flow is documented end to end in the
[OAuth quickstart](/guide/quickstart-oauth).
## 3. The eight tools
| Tool | Scope | When the agent calls it |
| ---------------------- | ------------ | ---------------------------------------------------------------------------------- |
| `discover_tools` | `tools:read` | First, whenever the task needs live or external data and the exact slug is unknown |
| `inspect_tool` | `tools:read` | Before running a tool whose input shape is not already known |
| `create_upload` | `tools:read` | Before `run_tool`, whenever the tool needs a file. It spends nothing |
| `run_tool` | `tools:run` | To actually execute a tool. This spends money |
| `get_run` | `tools:read` | To poll a `run_tool` call that came back with a `run_id` |
| `wallet_balance` | `tools:read` | To check available funds, or after an `insufficient_funds` error |
| `remember_tool_choice` | `tools:read` | Only when you explicitly say a choice should stick. It spends nothing |
| `forget_tool_choice` | `tools:read` | When you want to be offered the choice again |
That is the complete list. There is no per-tool MCP surface: the 55 catalog
tools are reached through `run_tool` by slug, which is what keeps the tool list
small enough for an agent to reason about.
### What the agent sees
`discover_tools` takes a plain-language `query` and an optional `limit`
(default 5, maximum 20). Each result carries a slug, guidance on when to use
it, its price and a fillable sample input, so the agent can usually skip
`inspect_tool`.
## Who picks the tool
You do. Goro never chooses one: `run_tool` takes an exact slug, so when several
tools can do a job, the choice happens in the agent.
By default it is not allowed to make that choice quietly. `discover_tools`
returns a `choose` field telling the agent to show you the candidates with
their prices and ask which you want. That matters because the prices are not
close: five tools can make you an image, from $0.01 to $0.27 a call, and being
charged for one you were never shown is not a good surprise.
Three things skip the question:
* **You named the tool.** "Use nano banana pro for this" is already an answer.
* **Only one tool matches.** Nothing to choose between, though the agent should
still tell you what it is about to spend.
* **You said to always use one.** Tell the agent "always use X for images",
"remember that", or "stop asking me", and it calls `remember_tool_choice`.
From then on `discover_tools` returns `your_preference` for that category and
the agent uses it without asking.
A preference is saved **only when you ask for one**. Picking a tool for a single
job is not a standing instruction, and treating it as one would mean you are
never offered the cheaper option again. One saved choice per category (image,
video, voice, search, social, maps, people, ecommerce). Say you want to pick
again and the agent calls `forget_tool_choice`.
This is an instruction to the agent, not a lock. Goro can tell a client to ask
you and can refuse to guess on your behalf, but it cannot reach into the
client and force a prompt. A well-behaved agent follows it; treat
`remember_tool_choice` as the reliable control, since that one is enforced
server-side.
The HTTP API and the CLI are unaffected: both already require you to name a
slug, so there is nothing for anyone to pick.
`run_tool` blocks for up to about 25 seconds. A fast tool returns its rows in
that same response. A slower one returns a `run_id` and an explicit
instruction to poll `get_run` until the status is terminal.
`wallet_balance` returns the available balance and a `top_up_url`, which is
what an agent should surface to a human when funds run out.
### Sending a file
One rule, and it matters more than it looks: an agent must never read a file
into the conversation in order to send it. Tool arguments pass through the
context window exactly like tool results do, so a 3 MB photograph sent as
`image_base64` is roughly a million tokens, gets truncated, and fails the run
with something that reads like file corruption.
`create_upload` is the way round it. It takes a `content_type`, returns a short
handle plus a URL to PUT the file to, and includes the exact `curl` to run. The
agent uploads the file with its own shell, then passes the handle as
`image_handle` in `run_tool`. The bytes never enter the conversation, the
ceiling goes from 3 MB to 10 MB, and the handle itself is about thirty
characters. Do not shrink the image to make it fit: size was never the problem
the upload path is solving. [Uploads](/api/uploads) documents the whole flow.
## 4. Errors an agent will meet
Tool errors carry the same `code` and `message` as the HTTP API, so one set of
instructions covers both surfaces.
| `code` | What the agent should do |
| -------------------- | -------------------------------------------------------------------------- |
| `validation_error` | Read the `errors` array, fix every field, retry once |
| `insufficient_funds` | Stop. Tell the human the amount and the `top_up_url` |
| `budget_exceeded` | Stop. The wallet is fine, a spend cap is blocking. Do not ask for a top-up |
| `not_found` | The slug does not exist. Run `discover_tools` again |
| `forbidden` | The token is missing the scope the tool needs. Reauthorise |
| `provider_error` | The tool failed and nothing was charged. Safe to retry |
## What this shares with the API
Everything. The MCP tools are thin wrappers over the same code paths as
`/v1/discover`, `/v1/inspect`, `/v1/uploads`, `/v1/run`, `/v1/runs/{id}` and
`/v1/wallet/balance`. Same catalog, same holds, same charges, same ledger.
Rows arrive in the `run_tool` response, or in the `get_run` poll that finds the
run finished. Polling a finished run is the supported way to collect a slow
result. Results are deleted once collected, and after 24 hours regardless, so
have the agent write down anything it will need later. When the result is a
media link, from a voice or image tool, have it download the file too: those
links expire on the same clock or on the model provider's.
The endpoints behind the six tools.