How do I install UpAPI?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does UpAPI need an API key?

The publisher lists these environment variables: UPAPI_API_KEY, UPAPI_TOOL_MODE.

When was UpAPI last checked?

Last checked 2026-11-09. All public upAPI operations as MCP tools: web scraping, search, screenshots, PDF, OCR and more.

UpAPI MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

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

Credentials from the publisher

UPAPI_API_KEY — upAPI API key (create one at https://app.upapi.io/dashboard/api-keys)
UPAPI_TOOL_MODE — Tool table: full (default), directory (curated named tools) or compact.

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

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

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.devinosolutions-upapi-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://app.upapi.io/api/mcp"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version: 0.2.0

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

@upapi/mcp

Every public upAPI operation as an MCP tool — web search, SERP, social profiles, dev-tool lookups, geo/finance data — so an agent can call them directly.

There are two ways to connect, and they differ only in how a call is authenticated:

	Local (stdio)	Hosted (HTTP)
Endpoint	`npx @upapi/mcp`	`https://app.upapi.io/api/mcp`
Auth	your `upapi_` API key	sign in with your upAPI account (OAuth)
Runs	on your machine	on upAPI
Best for	scripts, CI, self-hosted agents	Claude, IDEs, anything that speaks remote MCP

Both expose the same tools with the same schemas, and both bill the same quota.

Hosted — no install

Point any MCP client that supports remote servers at:

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

It will walk you through signing in to upAPI in a browser; there is no key to copy. With Claude Code:

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

Local — API key

Create a key at app.upapi.io → API Keys, then:

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

Claude Desktop (claude_desktop_config.json), Cursor, and Windsurf take the same thing as JSON:

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

Variable
`UPAPI_API_KEY`	required	an `upapi_` key
`UPAPI_BASE_URL`	optional	gateway origin, defaults to `https://api.upapi.io`
`UPAPI_TOOL_MODE`	optional	`compact` (default), `directory`, `claude` or `full` — see Tools

The key is never validated locally — only checked for presence, so a missing one fails immediately with a readable message instead of surfacing later as an unexplained 401 inside a tool call. Whether a key is real, expired, or over quota is answered at the gateway, the single place that answers it for every machine caller.

Tools

The hosted endpoint serves a compact table by default: two meta-tools plus a few always-on operations, a few kilobytes in total.

Tool	What it does
`search_ops`	Find operations by intent — returns slug, description, parameters, and quota cost
`call_op`	Run one operation by slug: `{ "slug": "github-repo.get", "input": { … } }`

A tool table is re-sent as context on every turn, so one tool per operation means tens of kilobytes of JSON Schema per turn and a table large enough to measurably degrade tool selection. search_ops + call_op stays flat as the catalog grows. web-search.post, github-repo.get, and wikipedia-article.get stay on the table as full tools so the common case needs no discovery round-trip.

There are two other tables. ?tools=full gives every operation its own tool:

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

?tools=directory gives a curated set of 11 named tools for the flagship operations — page-to-Markdown, screenshot, HTML-to-PDF, PDF text, OCR, transcription, GitHub repo, npm package, Wikipedia, currency — with read tools and write tools listed separately and no call_op. That is the shape AI-directory review criteria ask for (a catch-all dispatcher with a target parameter is a rejection, and so is a listing that advertises scraped sources, which is why the Maps trio and web search stay callable but are not listed there), and it is what the Claude Desktop Extension ships with. ?tools=claude is the same shape over the 8 operations upAPI computes itself (page-to-Markdown, screenshot, HTML-to-PDF, PDF text, OCR, transcription and its result, text analysis) — the Claude connector listing. The local stdio server takes the same names in UPAPI_TOOL_MODE, defaulting to compact — the same few-kilobyte shape the hosted endpoint defaults to. full remains available (UPAPI_TOOL_MODE=full) as the rollback for a client already configured against the one-tool-per-operation shape this server used to default to.

Every mode reaches exactly the same operations — the mode changes what is advertised, never what is allowed. Every tool in every mode carries readOnlyHint, destructiveHint, idempotentHint and openWorldHint, derived from what the worker does rather than from the slug's verb suffix. Operations are named after their slug with . and - replaced by _ (web-search.post → web_search_post), and each advertises the operation's real JSON Schema (formats, bounds, defaults, nullability), because that schema is generated from the worker's own model and passed through untouched.

The hosted server reaches the whole public catalog in every mode; since 2026-09-26 it withholds no category. The local (stdio) server and the Desktop Extension catch up in the next release: the published 0.2.0 bundles 63 operations and still withholds Social Media and Utility in directory mode.

directory mode only changes what is ADVERTISED — the curated flagship set a public listing (like the Claude Desktop Extension) shows.

Descriptions carry the quota cost, so an agent can budget:

Search the web… upAPI operation web-search.post (Search). Costs 25 units of monthly quota per call.

A failed operation comes back as a normal tool result with isError: true and text leading with upAPI's public error code — RATE_LIMITED, INVALID_INPUT, UPSTREAM_UNREACHABLE. A rate limit also states the wait in seconds. Nothing about a failing operation breaks the session.

No outputSchema is declared, deliberately: MCP requires a server that declares one to return matching structuredContent, and these outputs describe live third-party payloads. One unexpected null would turn a successful call into a protocol error.

Use it from Mastra

The tools work in a Mastra agent directly, without an MCP transport in between. @mastra/core and @mastra/mcp are optional peer dependencies — install them yourself, and import the bindings from the /mastra subpath. Nothing else in this package touches Mastra, which is what keeps a plain npm i @upapi/mcp (and the desktop-extension bundle built from it) small.

import { Agent } from '@mastra/core/agent';
import { createGatewayCaller } from '@upapi/mcp';
import { createUpapiTools } from '@upapi/mcp/mastra';

const agent = new Agent({
  name: 'researcher',
  instructions: 'Research topics using upAPI.',
  model: /* … */,
  tools: createUpapiTools({
    caller: createGatewayCaller({ apiKey: process.env.UPAPI_API_KEY! }),
  }),
});

Narrow the table with filter when an agent should only see part of the catalog:

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

`createUpapiMcpServer` — Code Mode by default

createUpapiMcpServer builds a Mastra MCPServer (@mastra/mcp, also an optional peer). Its default tool surface is Code Mode: search_tools + execute_typescript instead of one tool per operation — measured on the full 99-operation catalog, tools/list drops from 111,016 bytes to 1,069 bytes (99 tools → 2), because the table no longer grows with the catalog at all.

import { createGatewayCaller } from '@upapi/mcp';
import { createUpapiMcpServer } from '@upapi/mcp/mastra';

const server = createUpapiMcpServer({
  caller: createGatewayCaller({ apiKey: process.env.UPAPI_API_KEY! }),
});

await server.startStdio();

search_tools({ query? }) finds the operations this connection can reach and returns them as declare function external_<name>(...) TypeScript signatures.
execute_typescript({ code }) runs a short TypeScript program in an isolated QuickJS sandbox (@mastra/quickjs, another optional peer — no native binary, no filesystem/network/process access beyond the injected external_* functions). Batch several operations into one round trip with Promise.all instead of one tool call each. Killed after 30 seconds. A program that computes for more than 1.5 seconds without awaiting an external_* call, or for more than 5 seconds in total across all such stretches, is stopped with CPU_BUDGET_EXCEEDED: ..., because the sandbox shares the Node event loop with every other request the process serves. Needs quickjs-emscripten 0.31.0 (the exact version @mastra/quickjs 0.1.1 resolves) installed next to it. Both are loaded on the first execute_typescript call, so a server that never runs one (or uses the full surface) does not need them installed.

Every external_* call resolves to the exact same createUpapiTools(options) tool object the full surface (below) calls — there is no second auth path. A denied or failed operation call surfaces inside the sandbox as a thrown Error("<CODE>: <message>"), so the guest program's own try/catch can inspect and branch on the code; arguments that fail an operation's input schema throw INVALID_INPUT: <details> the same way. That is separate from a malformed execute_typescript input, which fails the call itself before the sandbox ever starts.

Set MCP_TOOL_SURFACE (or pass surface) to change what is advertised:

Value	Advertises	When to use it
`codemode` (default)	`search_tools` + `execute_typescript`	Any model that can write a few lines of TypeScript
`full`	One tool per operation — today's `createUpapiTools` table	Rollback switch, or a client already built against it
`both`	The union of the two	Exercising or migrating off of one surface mid-transition

MCP_TOOL_SURFACE=full node my-server.js   # one tool per operation, the pre-Code Mode shape

createUpapiMcpServer({ caller, surface: 'full' }); // same thing, set in code instead of env

instructions on the server carries the Code Mode contract automatically whenever a codemode tool is on the table (codemode and both) — a model was not told to write TypeScript against search_tools/execute_typescript otherwise.

Build your own server

caller is the only thing the tool table does not supply, which is what lets the same tools run over different transports:

import { startUpapiStdioServer, type Caller } from '@upapi/mcp';

const caller: Caller = async (slug, input) => {
  // resolve with the operation's output, or throw
  // { code, message, status?, retryAfterSeconds? }
};

await startUpapiStdioServer({ caller, mode: 'directory' });

For a web-standard Request/Response server (Next.js route, Worker, Hono), import the handler from the /http subpath — this is how app.upapi.io/api/mcp is built:

import { handleUpapiMcpRequest, type Caller } from '@upapi/mcp/http';

await handleUpapiMcpRequest(request, {
  caller,
  // mode defaults to the request's own `?tools=` parameter (compact unless `full`/`directory`)
  canExecute: true, // false hides every executable tool and refuses a call to one
  canSearch: true, // false hides `search_ops`
});

canExecute / canSearch are how a host projects its own authorization onto the table — upAPI maps them to the access token's ops:execute and ops:read scopes. Both default to true, so a host without a scope model is unaffected.

Prefer that subpath over the package root in a bundled or file-traced deployment: it reaches only the MCP SDK, while the root entry also pulls the stdio server in. Neither reaches Mastra — the bindings live behind @upapi/mcp/mastra precisely so that a build which never runs a Mastra agent never sees @mastra/core.

@upapi/sdk — the typed HTTP client, and the operation catalog this package's tool table is generated from
upapi.io/docs — operation reference

Where development happens

This repository is the published home of @upapi/mcp: it is what npm installs, and issues and pull requests are welcome here. The tool table is derived from the operation catalog in @upapi/sdk, which is itself generated from upAPI’s private operation definitions and synced automatically — so the set of tools changes upstream. The server, facade, error mapping and tests in these files are hand-written and are the code to change.

UpAPI

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install UpAPI?

Does UpAPI need an API key?

What transport does UpAPI use?

When was UpAPI last checked?

Documentation

@upapi/mcp

Hosted — no install

Local — API key

Tools

Use it from Mastra

`createUpapiMcpServer` — Code Mode by default

Build your own server

Related

Where development happens

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install UpAPI?

Does UpAPI need an API key?

What transport does UpAPI use?

When was UpAPI last checked?

Documentation

@upapi/mcp

Hosted — no install

Local — API key

Tools

Use it from Mastra

createUpapiMcpServer — Code Mode by default

Build your own server

Related

Where development happens

`createUpapiMcpServer` — Code Mode by default