MCP server

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

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.

Clients normally register themselves through dynamic client registration. Marketplaces whose tenant admins cannot (Microsoft 365 Copilot, Gemini Enterprise) get a static confidential client instead: the operator lists it in the OAUTH_STATIC_CLIENTS environment variable (client id, secret, name, exact redirect URIs, token-endpoint auth method), and every boot upserts it into the same client table. Such a client authenticates with its secret, never expires, and is left in place if it is later removed from the variable.

The hosted server serves every public operation, the same catalog as the REST gateway. Operations that write something, such as posting a comment or opening a mailbox, carry readOnlyHint: false, so your client can ask before it runs them.

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.

The hosted server serves every public operation. The local server catches up in the next @upapi/mcp release: 0.2.0 serves 63 operations and still withholds Social Media and Utility in directory mode.

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 except two: upAPI is a marketplace, so nearly every operation exists to reach a system upAPI does not own. text-analyze.post and email-generate-address.post run entirely inside the worker and make no network call, so they declare openWorldHint: false.

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

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%.