upAPI MCP

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

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

The Model Context Protocol lets an AI assistant call tools. upAPI publishes its operations over MCP, so an operation becomes a tool the assistant can invoke — with your key, your quota and the same schemas as the REST gateway.

There are two ways to connect, described below. They differ in how you authorize and in how much of the catalog they serve. For the configuration to paste into a specific client, see Connect an MCP client.

Hosted server [#hosted-server]

https://app.upapi.io/api/mcp speaks MCP over streamable HTTP and authorizes over OAuth 2.1 with PKCE, against the same accounts system as the dashboard. A client connects by signing in through a browser, so no API key is ever written into a config file.

Each request re-establishes your identity from the access token, and tool calls execute on exactly the path the marketplace try-it panel uses — the same plan gating and the same meter. A guest session cannot connect; see Connect an MCP client for why.

The hosted server serves the catalog minus the Social Media and Utility categories — the social profile/post readers and the two email-read-verification-* operations. This is the surface AI directories list publicly, and those operations read other people's personal data or automate signup flows, which is a reasonable thing for you to do with your own key and not a reasonable thing to offer a stranger's assistant on one OAuth click. They are not going anywhere: use them on the REST gateway, in the try-it panel, or through the local server below.

Local server [#local-server]

The upapi-mcp command speaks MCP over stdio and forwards each tool call to api.upapi.io with your API key. It runs on your machine, alongside the client.

It authenticates with the key in UPAPI_API_KEY and validates nothing itself — your key is checked at the same gateway choke point as any other call, so an MCP tool call is metered and rate-limited exactly like the equivalent curl. Point it at a different gateway origin with UPAPI_BASE_URL if you need to.

Because you install it deliberately with your own key, the local server serves the whole catalog, including the categories the hosted server withholds.

What the tools look like [#what-the-tools-look-like]

Each public operation becomes one tool, with the operation's input schema as its parameter schema. The assistant sees the same field names, types and descriptions the marketplace shows you, so it can fill arguments without guessing.

How many of those tools are advertised at once is a choice — compact, directory or full, set on the URL for the hosted server and in UPAPI_TOOL_MODE for the local one. All three are built from the same tool table, so the mode changes what is listed and never what is reachable. See Which tools you get.

Every tool declares the four MCP behavioural hints — readOnlyHint, destructiveHint, idempotentHint and openWorldHint — and they describe what the worker actually does rather than what the slug's .get/.post suffix suggests. openWorldHint is true on every operation: upAPI is a marketplace, so each one exists to reach a system upAPI does not own.

A tool's name is not the slug: MCP names have to be identifier-safe, so it is the operation id — the slug with dots and hyphens replaced by underscores. github-trending.get is the tool github_trending_get. The tool's description names the slug it maps to, and what a call costs, so you can cross-read these docs from a tools/list dump.

Results come back as the operation's output object, JSON-encoded into a text block — no tool declares an outputSchema, and none returns structuredContent. That is deliberate: MCP obliges a server that declares an output schema to return matching structured content, and these outputs describe live third-party payloads, where one unexpected null would turn a successful call into a protocol error. Failures arrive with the standard error code, which means an assistant can tell "you are out of quota" apart from "that operation does not exist" and say something useful about it.

Cost [#cost]

MCP tool calls are ordinary gateway calls: they consume the operation's weighted units and count against the same monthly quota as your application traffic.

Worth knowing before you point an agent at the catalog: an assistant exploring on its own can spend a lot more than a deliberate script, and the heaviest operations in the catalog cost 20 units per call. Check /api/usage after a long session, and keep an eye on the quota notifications at 70% and 90%.