Goro
Uma conexão MCP que dá ao seu agente 62 ferramentas do mundo real: busca na web, scraping, dados sociais, enriquecimento, imagem, vídeo e voz. Pague por chamada, US$ 1 grátis para começar.
Documentação
Para agentes de IA: MCP
Adicione o Goro ao Claude, Cursor ou qualquer cliente MCP como conector, e seu agente terá todo o catálogo como seis ferramentas.
O Goro executa um servidor MCP remoto. Adicione uma URL ao seu cliente e o agente terá seis ferramentas que alcançam todo o catálogo, com o mesmo saldo e os mesmos preços da API HTTP.
https://mcp.usegoro.ai/mcp
1. Adicione o conector
No Claude, Cursor ou qualquer cliente MCP que suporte servidores remotos, adicione um conector personalizado com a URL acima. O cliente cuida do resto: ele se registra, abre a tela de consentimento do Goro em um navegador e armazena o token que recebe de volta.
O transporte é HTTP Streamable. O servidor é sem estado por requisição, então não há sessão para manter viva e nada para reconectar.
2. Autorize-o
A tela de consentimento pede uma chave de API do Goro, a goro_live_ de app.usegoro.ai. Essa chave identifica de qual workspace e saldo o conector gastará. Cole-a uma vez, aprove e o cliente estará conectado.
Existem dois escopos, e um cliente que não pede uma concessão mais restrita recebe ambos:
| Escopo | Concessões |
|---|---|
tools:read | discover_tools, inspect_tool, create_upload, get_run, wallet_balance, remember_tool_choice, forget_tool_choice |
tools:run | run_tool |
Os tokens de acesso duram uma hora e o cliente os renova silenciosamente. Os tokens de atualização duram 30 dias e são rotacionados a cada uso.
Construindo o cliente você mesmo em vez de usar um existente? O fluxo OAuth é documentado de ponta a ponta no [início rápido do OAuth](/guide/quickstart-oauth).3. As oito ferramentas
| Ferramenta | Escopo | Quando o agente a chama |
|---|---|---|
discover_tools | tools:read | Primeiro, sempre que a tarefa precisar de dados ao vivo ou externos e o slug exato for desconhecido |
inspect_tool | tools:read | Antes de executar uma ferramenta cuja forma de entrada ainda não é conhecida |
create_upload | tools:read | Antes de run_tool, sempre que a ferramenta precisar de um arquivo. Não gasta nada |
run_tool | tools:run | Para realmente executar uma ferramenta. Isso gasta dinheiro |
get_run | tools:read | Para consultar uma chamada run_tool que retornou com um run_id |
wallet_balance | tools:read | Para verificar fundos disponíveis, ou após um erro insufficient_funds |
remember_tool_choice | tools:read | Somente quando você explicitamente disser que uma escolha deve permanecer. Não gasta nada |
forget_tool_choice | tools:read | Quando você quiser que a escolha seja oferecida novamente |
Essa é a lista completa. Não há superfície MCP por ferramenta: as 70 ferramentas do catálogo são alcançadas por meio de run_tool por slug, o que mantém a lista de ferramentas pequena o suficiente para um agente raciocinar sobre ela.
O que o agente vê
discover_tools aceita um query em linguagem simples e um limit opcional (padrão 5, máximo 20). Cada resultado traz um slug, orientação sobre quando usá-lo, seu preço e um exemplo de entrada preenchível, então o agente geralmente pode pular inspect_tool.
Quem escolhe a ferramenta
Você. O Goro nunca escolhe uma: run_tool aceita um slug exato, então quando várias ferramentas podem fazer um trabalho, a escolha acontece no agente.
Por padrão, não é permitido fazer essa escolha silenciosamente. discover_tools retorna um campo choose dizendo ao agente para mostrar os candidatos com seus preços e perguntar qual você quer. Isso importa porque os preços não são próximos: cinco ferramentas podem criar uma imagem, de $0.01 a $0.27 por chamada, e ser cobrado por uma que nunca foi mostrada não é uma boa surpresa.
Três coisas pulam a pergunta:
- Você nomeou a ferramenta. "Use nano banana pro para isso" já é uma resposta.
- Apenas uma ferramenta corresponde. Não há nada para escolher, embora o agente ainda deva informar o que está prestes a gastar.
- Você disse para sempre usar uma. Diga ao agente "sempre use X para imagens", "lembre disso" ou "pare de me perguntar", e ele chama
remember_tool_choice. A partir daí,discover_toolsretornayour_preferencepara essa categoria e o agente a usa sem perguntar.
Uma preferência é salva somente quando você pede uma. Escolher uma ferramenta para um único trabalho não é uma instrução permanente, e tratá-la como tal significaria que você nunca mais receberia a opção mais barata. Uma escolha salva por categoria (imagem, vídeo, voz, busca, social, mapas, pessoas, ecommerce). Diga que quer escolher novamente e o agente chama forget_tool_choice.
A API HTTP e a CLI não são afetadas: ambas já exigem que você nomeie um slug, então não há nada para ninguém escolher.
run_tool bloqueia por até cerca de 25 segundos. Uma ferramenta rápida retorna suas linhas na mesma resposta. Uma mais lenta retorna um run_id e uma instrução explícita para consultar get_run até que o status seja terminal.
wallet_balance retorna o saldo disponível e um top_up_url, que é o que um agente deve mostrar a um humano quando os fundos acabam.
Enviando um arquivo
Uma regra, e importa mais do que parece: um agente nunca deve ler um arquivo na conversa para enviá-lo. Os argumentos da ferramenta passam pela janela de contexto exatamente como os resultados da ferramenta, então uma fotografia de 3 MB enviada como image_base64 é aproximadamente um milhão de tokens, é truncada e falha na execução com algo que parece corrupção de arquivo.
create_upload é o caminho para contornar isso. Ele aceita um content_type, retorna um handle curto mais uma URL para fazer PUT do arquivo, e inclui o curl exato para executar. O agente envia o arquivo com seu próprio shell, então passa o handle como image_handle em run_tool. Os bytes nunca entram na conversa, o limite vai de 3 MB para 10 MB, e o handle em si tem cerca de trinta caracteres. Não reduza a imagem para caber: o tamanho nunca foi o problema que o caminho de upload resolve. Uploads documenta todo o fluxo.
4. Erros que um agente encontrará
Os erros de ferramenta carregam os mesmos code e message que a API HTTP, então um conjunto de instruções cobre ambas as superfícies.
code | O que o agente deve fazer |
|---|---|
validation_error | Leia o array errors, corrija cada campo, tente novamente uma vez |
insufficient_funds | Pare. Diga ao humano o valor e o top_up_url |
budget_exceeded | Pare. A carteira está ok, um limite de gastos está bloqueando. Não peça recarga |
not_found | O slug não existe. Execute discover_tools novamente |
forbidden | O token está sem o escopo que a ferramenta precisa. Reautorize |
provider_error | A ferramenta falhou e nada foi cobrado. Seguro tentar novamente |
O que isso compartilha com a API
Tudo. As ferramentas MCP são wrappers finos sobre os mesmos caminhos de código que /v1/discover, /v1/inspect, /v1/uploads, /v1/run, /v1/runs/{id} e /v1/wallet/balance. Mesmo catálogo, mesmas retenções, mesmas cobranças, mesmo razão.
As linhas chegam na resposta run_tool, ou na consulta get_run que encontra a execução concluída. Consultar uma execução concluída é a forma suportada de coletar um resultado lento. Os resultados são excluídos após a coleta, e após 24 horas independentemente, então faça o agente anotar qualquer coisa que precisará depois. Quando o resultado for um link de mídia, de uma ferramenta de voz ou imagem, faça-o baixar o arquivo também: esses links expiram no mesmo relógio ou no do provedor do modelo.