upAPI

@upapi/mcp

Toda operação pública da upAPI como uma ferramenta MCP — busca na web, SERP, perfis sociais, consultas de ferramentas de desenvolvimento, dados geográficos/financeiros — para que um agente possa chamá-las diretamente.

Existem duas formas de conectar, e elas diferem apenas em como uma chamada é autenticada:

	Local (stdio)	Hospedado (HTTP)
Endpoint	npx @upapi/mcp	https://app.upapi.io/api/mcp
Auth	sua chave de API upapi_	entre com sua conta upAPI (OAuth)
Execução	na sua máquina	na upAPI
Melhor para	scripts, CI, agentes auto-hospedados	Claude, IDEs, qualquer coisa que fale MCP remoto

Ambos expõem as mesmas ferramentas com os mesmos esquemas, e ambos cobram da mesma cota.

Hospedado — sem instalação

Aponte qualquer cliente MCP que suporte servidores remotos para:

https://app.upapi.io/api/mcp

Ele vai guiá-lo pelo login na upAPI em um navegador; não há chave para copiar. Com o Claude Code:

claude mcp add --transport http upapi https://app.upapi.io/api/mcp

Local — chave de API

Crie uma chave em app.upapi.io → API Keys, depois:

claude mcp add upapi -e UPAPI_API_KEY=upapi_xxx -- npx -y @upapi/mcp

Claude Desktop (claude_desktop_config.json), Cursor e Windsurf aceitam o mesmo em JSON:

{
  "mcpServers": {
    "upapi": {
      "command": "npx",
      "args": ["-y", "@upapi/mcp"],
      "env": { "UPAPI_API_KEY": "upapi_xxx" }
    }
  }
}

Variável
UPAPI_API_KEY	obrigatória	uma chave upapi_
UPAPI_BASE_URL	opcional	origem do gateway, padrão é https://api.upapi.io

A chave nunca é validada localmente — apenas verificada quanto à presença, então uma chave ausente falha imediatamente com uma mensagem legível em vez de aparecer mais tarde como um 401 inexplicável dentro de uma chamada de ferramenta. Se uma chave é real, expirada ou acima da cota é respondido no gateway, o único lugar que responde isso para cada chamador de máquina.

Ferramentas

O endpoint hospedado serve uma tabela compacta por padrão: duas meta-ferramentas mais algumas operações sempre ativas, alguns kilobytes no total.

Ferramenta	O que faz
search_ops	Encontra operações por intenção — retorna slug, descrição, parâmetros e custo de cota
call_op	Executa uma operação por slug: { "slug": "github-repo.get", "input": { … } }

Uma tabela de ferramentas é reenviada como contexto a cada turno, então uma ferramenta por operação significa dezenas de kilobytes de JSON Schema por turno e uma tabela grande o suficiente para degradar de forma mensurável a seleção de ferramentas. search_ops + call_op permanece estável conforme o catálogo cresce. web-search.post, github-repo.get, e wikipedia-article.get permanecem na tabela como ferramentas completas para que o caso comum não precise de uma viagem de descoberta.

Quer cada operação como sua própria ferramenta? Adicione ?tools=full:

claude mcp add --transport http upapi 'https://app.upapi.io/api/mcp?tools=full'

Ambos os modos alcançam exatamente as mesmas operações — o modo muda o que é anunciado, nunca o que é permitido. As operações são nomeadas conforme seu slug com . e - substituídos por _ (web-search.post → web_search_post), e cada uma anuncia o JSON Schema real da operação (formatos, limites, padrões, anulabilidade), porque esse esquema é gerado a partir do modelo do próprio worker e passado sem alterações.

O servidor local (stdio) sempre serve uma ferramenta por operação, e o catálogo inteiro: ele é instalado deliberadamente, com sua própria chave, em um cliente de sua escolha.

As descrições carregam o custo de cota, para que um agente possa fazer orçamento:

Busca na web… operação upAPI web-search.post (Search). Custa 25 unidades da cota mensal por chamada.

Uma operação com falha retorna como um resultado normal de ferramenta com isError: true e texto começando com o código de erro público da upAPI — RATE_LIMITED, INVALID_INPUT, UPSTREAM_UNREACHABLE. Um limite de taxa também informa o tempo de espera em segundos. Nada sobre uma operação com falha quebra a sessão.

Nenhum outputSchema é declarado, deliberadamente: MCP exige que um servidor que declare um retorne structuredContent correspondentes, e essas saídas descrevem payloads ao vivo de terceiros. Um null inesperado transformaria uma chamada bem-sucedida em um erro de protocolo.

Use com Mastra

As ferramentas funcionam diretamente em um agente Mastra, sem um transporte MCP no meio:

import { Agent } from '@mastra/core/agent';
import { createGatewayCaller, createUpapiTools } from '@upapi/mcp';

const agent = new Agent({
  name: 'researcher',
  instructions: 'Research topics using upAPI.',
  model: /* … */,
  tools: createUpapiTools({
    caller: createGatewayCaller({ apiKey: process.env.UPAPI_API_KEY! }),
  }),
});

Reduza a tabela com filter quando um agente deve ver apenas parte do catálogo:

createUpapiTools({
  caller,
  filter: (op) => op.category === 'Search',
});

Construa seu próprio servidor

caller é a única coisa que a tabela de ferramentas não fornece, o que permite que as mesmas ferramentas rodem em diferentes transportes:

import { createUpapiMcpServer, type Caller } from '@upapi/mcp';

const caller: Caller = async (slug, input) => {
  // resolve with the operation's output, or throw
  // { code, message, status?, retryAfterSeconds? }
};

await createUpapiMcpServer({ caller }).startStdio();

Para um servidor Request/Response padrão da web (rota Next.js, Worker, Hono), importe o handler do subcaminho /http — é assim que app.upapi.io/api/mcp é construído:

import { handleUpapiMcpRequest, type Caller } from '@upapi/mcp/http';

await handleUpapiMcpRequest(request, {
  caller,
  // mode defaults to the request's own `?tools=` parameter (compact unless `full`)
  canExecute: true, // false hides every executable tool and refuses a call to one
  canSearch: true, // false hides `search_ops`
});

canExecute / canSearch são como um host projeta sua própria autorização na tabela — a upAPI os mapeia para os escopos ops:execute e ops:read do token de acesso. Ambos padrão como true, então um host sem modelo de escopo não é afetado.

Prefira esse subcaminho em vez da raiz do pacote em uma implantação empacotada ou com rastreamento de arquivos. A entrada raiz reexporta os bindings do Mastra, então importar o handler dela puxa @mastra/core e @mastra/mcp para um build que nunca executa um agente Mastra; @upapi/mcp/http alcança apenas o SDK MCP.

Relacionados

• @upapi/sdk — o cliente HTTP tipado, e o catálogo de operações do qual a tabela de ferramentas deste pacote é gerada
• upapi.io/docs — referência de operações

Onde o desenvolvimento acontece

Este repositório é o lar publicado de @upapi/mcp: é o que o npm instala, e issues e pull requests são bem-vindos aqui. A tabela de ferramentas é derivada do catálogo de operações em @upapi/sdk, que por sua vez é gerado a partir das definições privadas de operações da upAPI e sincronizado automaticamente — então o conjunto de ferramentas muda a montante. O servidor, a fachada, o mapeamento de erros e os testes nesses arquivos são escritos à mão e são o código a ser alterado.