upAPI MCP
Call a catalog of ready-to-use APIs through one upAPI account and key, without signing up for each upstream service. Remote server with OAuth sign-in.
Hosted MCP Server
npx add-mcp 'https://app.upapi.io/api/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
MCP server (https://upapi.io/docs/mcp)
Onboard your AI agent to upAPI: Claude, ChatGPT, or add https://app.upapi.io/api/mcp (HTTP) to any other MCP client and sign in with your upAPI account.
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.
A request with no valid credential is answered 401 with a WWW-Authenticate header that points at
the OAuth resource metadata, which is how a client discovers where to sign in. A client that keeps
sending requests with no bearer token at all from one IP address (a misconfigured agent
retrying in a loop) is answered 429 RATE_LIMITED with a Retry-After header after its first 20
such requests in a minute, or 300 in an hour. The 429 keeps the WWW-Authenticate header, and
Retry-After is the time until the window that turned the request away closes. Requests the
minute limit turns away still count toward the hourly 300, so a client that keeps hammering through
a 429 can be pushed into an hour-long wait: stop and honor Retry-After.
Only a request with no bearer token is limited. A request that carries one is never counted and
never answered 429, whether the token is valid, expired or unknown: an expired token still gets
the 401 that tells your client to refresh it. The OAuth discovery endpoints (the authorization
server and protected-resource metadata) are separate routes and are not limited.
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 [#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 and every account tool. The local server
gets new tools when you update @upapi/mcp.
Account tools [#account-tools]
Besides the catalog, the server has account tools that do everything the dashboard does: billing and plan changes, API keys, team, support, connected apps, your own APIs and hosted functions, products, referral and usage. The full list is generated from the tool registry on MCP tools.
On the consent screen you choose which permission tiers a connection holds. All are on by default.
A tool outside the connection's tiers answers SCOPE_MISSING and next points at request_scopes,
which returns a link where you grant more. Deleting or cancelling answers once with
CONFIRMATION_REQUIRED and a confirmToken; repeat the call with it to proceed. A step that needs a
browser, such as checkout, comes back as a one-time link.
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 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 [#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 25 units per call. Check
/api/usage after a long session, and keep an eye on the
quota notifications at 70% and 90%.