Skip to main content
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.

​
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. 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: 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.

​
3. The eight tools

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.01to0.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 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.

​
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.

Full API reference

The endpoints behind the six tools.