upAPI MCP

npx add-mcp 'https://app.upapi.io/api/mcp'

Servidor MCP (https://upapi.io/docs/mcp)

O Model Context Protocol permite que um assistente de IA chame ferramentas. A upAPI publica suas operações via MCP, então uma operação se torna uma ferramenta que o assistente pode invocar — com sua chave, sua cota e os mesmos esquemas do gateway REST.

Existem duas formas de conectar, descritas abaixo. Elas diferem em como você autoriza e em quanto do catálogo elas atendem. Para a configuração que deve ser colada em um cliente específico, veja Conectar um cliente MCP.

Servidor hospedado [#hosted-server]

https://app.upapi.io/api/mcp fala MCP via HTTP streamable e autoriza via OAuth 2.1 com PKCE, contra o mesmo sistema de contas do painel. Um cliente conecta-se fazendo login através de um navegador, então nenhuma chave de API é gravada em um arquivo de configuração.

Cada requisição restabelece sua identidade a partir do token de acesso, e as chamadas de ferramenta executam exatamente no caminho que o painel de teste do marketplace usa — o mesmo controle de plano e o mesmo medidor. Uma sessão de convidado não pode conectar; veja Conectar um cliente MCP para saber o motivo.

O servidor hospedado atende ao catálogo menos as categorias Mídias Sociais e Utilidades — os leitores de perfil/post social e as duas operações email-read-verification-*. Essa é a superfície que os diretórios de IA listam publicamente, e essas operações leem dados pessoais de outras pessoas ou automatizam fluxos de cadastro, o que é algo razoável para você fazer com sua própria chave e não algo razoável para oferecer ao assistente de um estranho com um clique de OAuth. Elas não vão a lugar nenhum: use-as no gateway REST, no painel de teste, ou através do servidor local abaixo.

Servidor local [#local-server]

O comando upapi-mcp fala MCP via stdio e encaminha cada chamada de ferramenta para api.upapi.io com sua chave de API. Ele roda na sua máquina, junto com o cliente.

Ele autentica com a chave em UPAPI_API_KEY e não valida nada por conta própria — sua chave é verificada no mesmo ponto de controle do gateway que qualquer outra chamada, então uma chamada de ferramenta MCP é medida e limitada exatamente como o curl equivalente. Aponte-o para uma origem de gateway diferente com UPAPI_BASE_URL se precisar.

Como você o instala deliberadamente com sua própria chave, o servidor local atende ao catálogo inteiro, incluindo as categorias que o servidor hospedado retém.

Como as ferramentas se parecem [#what-the-tools-look-like]

Cada operação pública se torna uma ferramenta, com o esquema de entrada da operação como seu esquema de parâmetros. O assistente vê os mesmos nomes de campos, tipos e descrições que o marketplace mostra a você, então ele pode preencher argumentos sem adivinhar.

Quantas dessas ferramentas são anunciadas de uma vez é uma escolha — compact, directory ou full, definida na URL para o servidor hospedado e em UPAPI_TOOL_MODE para o local. Todas as três são construídas a partir da mesma tabela de ferramentas, então o modo muda o que é listado e nunca o que é alcançável. Veja Quais ferramentas você obtém.

Cada ferramenta declara as quatro dicas comportamentais do MCP — readOnlyHint, destructiveHint, idempotentHint e openWorldHint — e elas descrevem o que o trabalhador realmente faz, em vez do que o sufixo .get/.post do slug sugere. openWorldHint é verdadeiro em todas as operações: a upAPI é um marketplace, então cada uma existe para alcançar um sistema que a upAPI não possui.

O nome de uma ferramenta não é o slug: nomes MCP precisam ser seguros para identificadores, então é o id da operação — o slug com pontos e hífens substituídos por sublinhados. github-trending.get é a ferramenta github_trending_get. A descrição da ferramenta nomeia o slug ao qual ela mapeia, e quanto custa uma chamada, para que você possa ler estas documentações de forma cruzada a partir de um dump de tools/list.

Os resultados voltam como o objeto de saída da operação, codificado em JSON em um bloco de texto — nenhuma ferramenta declara um outputSchema, e nenhuma retorna structuredContent. Isso é deliberado: o MCP obriga um servidor que declara um esquema de saída a retornar conteúdo estruturado correspondente, e essas saídas descrevem payloads de terceiros ao vivo, onde um null inesperado transformaria uma chamada bem-sucedida em um erro de protocolo. Falhas chegam com o código de erro padrão, o que significa que um assistente pode distinguir "você está sem cota" de "essa operação não existe" e dizer algo útil sobre isso.

Custo [#cost]

Chamadas de ferramentas MCP são chamadas comuns de gateway: elas consomem as unidades ponderadas da operação e contam contra a mesma cota mensal que seu tráfego de aplicação.

Vale saber antes de apontar um agente para o catálogo: um assistente explorando por conta própria pode gastar muito mais do que um script deliberado, e as operações mais pesadas do catálogo custam 20 unidades por chamada. Verifique /api/usage após uma sessão longa, e fique de olho nas notificações de cota em 70% e 90%.