upAPI

@upapi/mcp

Cada operación pública de upAPI como una herramienta MCP — búsqueda web, SERP, perfiles sociales, consultas de herramientas de desarrollo, datos geo/financieros — para que un agente pueda llamarlas directamente.

Hay dos formas de conectarse, y solo difieren en cómo se autentica una llamada:

	Local (stdio)	Alojado (HTTP)
Endpoint	npx @upapi/mcp	https://app.upapi.io/api/mcp
Auth	tu clave de API de upapi_	inicia sesión con tu cuenta de upAPI (OAuth)
Ejecución	en tu máquina	en upAPI
Ideal para	scripts, CI, agentes autoalojados	Claude, IDEs, cualquier cosa que hable MCP remoto

Ambos exponen las mismas herramientas con los mismos esquemas, y ambos consumen la misma cuota.

Alojado — sin instalación

Apunta cualquier cliente MCP que admita servidores remotos a:

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

Te guiará para iniciar sesión en upAPI en un navegador; no hay clave que copiar. Con Claude Code:

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

Local — clave de API

Crea una clave en app.upapi.io → API Keys, luego:

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

Claude Desktop (claude_desktop_config.json), Cursor y Windsurf aceptan lo mismo como JSON:

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

Variable
UPAPI_API_KEY	requerida	una clave de upapi_
UPAPI_BASE_URL	opcional	origen del gateway, por defecto https://api.upapi.io

La clave nunca se valida localmente — solo se verifica su presencia, por lo que una clave faltante falla inmediatamente con un mensaje legible en lugar de aparecer más tarde como un 401 inexplicable dentro de una llamada de herramienta. Si una clave es real, está vencida o supera la cuota, se responde en el gateway, el único lugar que responde por cada llamador de máquina.

Herramientas

El endpoint alojado sirve una tabla compacta por defecto: dos meta-herramientas más unas pocas operaciones siempre activas, unos pocos kilobytes en total.

Herramienta	Qué hace
search_ops	Encuentra operaciones por intención — devuelve slug, descripción, parámetros y costo de cuota
call_op	Ejecuta una operación por slug: { "slug": "github-repo.get", "input": { … } }

Una tabla de herramientas se reenvía como contexto en cada turno, por lo que una herramienta por operación significa decenas de kilobytes de JSON Schema por turno y una tabla lo suficientemente grande como para degradar de forma medible la selección de herramientas. search_ops + call_op se mantiene plana a medida que crece el catálogo. web-search.post, github-repo.get y wikipedia-article.get permanecen en la tabla como herramientas completas para que el caso común no necesite un viaje de ida y vuelta de descubrimiento.

¿Quieres cada operación como su propia herramienta? Añade ?tools=full:

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

Ambos modos alcanzan exactamente las mismas operaciones — el modo cambia lo que se anuncia, nunca lo que se permite. Las operaciones se nombran según su slug con . y - reemplazados por _ (web-search.post → web_search_post), y cada una anuncia el JSON Schema real de la operación (formatos, límites, valores por defecto, nulabilidad), porque ese esquema se genera desde el propio modelo del worker y se pasa sin modificaciones.

El servidor local (stdio) siempre sirve una herramienta por operación, y todo el catálogo: se instala deliberadamente, con tu propia clave, en un cliente que elijas.

Las descripciones incluyen el costo de cuota, para que un agente pueda presupuestar:

Busca en la web… operación upAPI web-search.post (Search). Cuesta 25 unidades de cuota mensual por llamada.

Una operación fallida regresa como un resultado normal de herramienta con isError: true y texto que comienza con el código de error público de upAPI — RATE_LIMITED, INVALID_INPUT, UPSTREAM_UNREACHABLE. Un límite de tasa también indica la espera en segundos. Nada sobre una operación fallida rompe la sesión.

No se declara outputSchema, deliberadamente: MCP requiere que un servidor que lo declare devuelva structuredContent coincidentes, y estas salidas describen cargas útiles de terceros en vivo. Un null inesperado convertiría una llamada exitosa en un error de protocolo.

Úsalo desde Mastra

Las herramientas funcionan directamente en un agente Mastra, sin un transporte MCP en el medio:

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! }),
  }),
});

Reduce la tabla con filter cuando un agente solo deba ver parte del catálogo:

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

Construye tu propio servidor

caller es lo único que la tabla de herramientas no proporciona, que es lo que permite que las mismas herramientas se ejecuten sobre 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 un servidor Request/Response estándar web (ruta Next.js, Worker, Hono), importa el handler desde la subruta /http — así es como se construye app.upapi.io/api/mcp:

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 son cómo un host proyecta su propia autorización sobre la tabla — upAPI los mapea a los alcances ops:execute y ops:read del token de acceso. Ambos son true por defecto, por lo que un host sin modelo de alcances no se ve afectado.

Prefiere esa subruta sobre la raíz del paquete en una implementación empaquetada o con seguimiento de archivos. La entrada raíz reexporta los enlaces de Mastra, por lo que importar el handler desde ella arrastra @mastra/core y @mastra/mcp a una compilación que nunca ejecuta un agente Mastra; @upapi/mcp/http alcanza solo el SDK de MCP.

Relacionado

• @upapi/sdk — el cliente HTTP tipado, y el catálogo de operaciones del que se genera la tabla de herramientas de este paquete
• upapi.io/docs — referencia de operaciones

Dónde ocurre el desarrollo

Este repositorio es el hogar publicado de @upapi/mcp: es lo que npm instala, y los problemas y solicitudes de extracción son bienvenidos aquí. La tabla de herramientas se deriva del catálogo de operaciones en @upapi/sdk, que a su vez se genera a partir de las definiciones de operaciones privadas de upAPI y se sincroniza automáticamente — por lo que el conjunto de herramientas cambia aguas arriba. El servidor, la fachada, el mapeo de errores y las pruebas en estos archivos están escritos a mano y son el código a modificar.