단일 통합 API 게이트웨이를 통해 AI agent가 웹 스크래핑, 검색, 소셜 미디어 조회 및 파일 작업을 수행할 수 있도록 지원합니다.
다른 이름 DevinoSolutions/upapi-mcp, upapi-mcp, @upapi/mcp
- 스타
- 0
- Tools
- 2
- 다운로드, 30일
- —
- 최신 버전
- 0.2.0
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
upAPI MCP란?
단일 통합 API 게이트웨이를 통해 AI agent가 웹 스크래핑, 검색, 소셜 미디어 조회 및 파일 작업을 수행할 수 있도록 지원합니다. 2개 도구를 제공합니다. 예: search_ops, call_op.
프로젝트 README에서 생성된 요약
upAPI MCP server 정보
upAPI는 AI agent가 단일 인터페이스를 통해 다양한 호스팅된 작업에 액세스할 수 있도록 하는 통합 API 게이트웨이 역할을 합니다. 개발자는 수십 개의 개별 서비스를 통합하는 대신, 하나의 API key만 사용하여 웹 검색, 소셜 미디어 조회, 금융 데이터, 지도 및 파일 작업을 위한 도구에 접근할 수 있습니다. 이러한 방식은 기능이 추가되더라도 통합 복잡도가 증가하지 않도록 보장합니다.
사용자는 API key를 사용하는 로컬 stdio 설정이나 OAuth를 사용하는 호스팅된 HTTP 엔드포인트를 통해 연결할 수 있습니다. 이 서버는 컨텍스트 윈도우 제한을 관리하기 위해 다양한 도구 모드를 지원합니다. compact mode는 스키마를 작게 유지하기 위해 search 및 call 도구를 사용하는 반면, full mode는 모든 작업에 대해 개별 도구를 제공합니다. Claude Desktop, Cursor, Windsurf와 같은 클라이언트와 함께 사용하거나 Mastra agent에 직접 통합하도록 설계되었습니다.
활용 사례
- 1배치 작업 실행개발자는 TypeScript를 사용하여 여러 API 호출을 한 번의 왕복으로 실행함으로써 시간을 절약할 수 있습니다.
- 2API 할당량 관리agent가 작업 비용을 확인하여 월간 예산 내에서 작동하도록 관리할 수 있습니다.
- 3웹 페이지 콘텐츠 추출agent가 웹 페이지를 Markdown으로 변환하거나 사이트의 스크린샷을 찍을 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
upAPI MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 upAPI MCP 설치
$ claude mcp add --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp -- npx -y @upapi/mcpCursor에 upAPI MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}VS Code에 upAPI MCP 설치
.vscode/mcp.json
{
"servers": {
"upapi-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}VS Code CLI에 upAPI MCP 설치
$ code --add-mcp '{"name":"upapi-mcp","type":"stdio","command":"npx","args":["-y","@upapi/mcp"],"env":{"UPAPI_API_KEY":"<YOUR_UPAPI_API_KEY>"}}'Claude Desktop에 upAPI MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}Codex에 upAPI MCP 설치
$ codex mcp add upapi-mcp --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' -- npx -y @upapi/mcpCodex config.toml에 upAPI MCP 설치
~/.codex/config.toml
[mcp_servers.upapi-mcp] command = "npx" args = ["-y", "@upapi/mcp"] [mcp_servers.upapi-mcp.env] UPAPI_API_KEY = "<YOUR_UPAPI_API_KEY>"
Gemini CLI에 upAPI MCP 설치
$ gemini mcp add -s user -e 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp npx -- -y @upapi/mcpGemini settings.json에 upAPI MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}upAPI MCP 도구 2
README에서 감지됨search_opscall_op
| search_ops | — | |
| call_op | — |
구성
UPAPI_API_KEY필수비밀upAPI API key (create one at https://app.upapi.io/dashboard/api-keys)
MCP_TOOL_SURFACEUPAPI_TOOL_MODETool table: full (default), directory (curated named tools) or compact.
| 이름 | 설명 | 유형 |
|---|---|---|
| UPAPI_API_KEY | upAPI API key (create one at https://app.upapi.io/dashboard/api-keys) | 필수비밀 |
| MCP_TOOL_SURFACE | — | |
| UPAPI_TOOL_MODE | Tool table: full (default), directory (curated named tools) or compact. |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용통과
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기@upapi/mcp
upAPI (upapi.io) is an API marketplace and gateway. One API key and one pooled quota call every operation in the catalog — social media, search, maps, finance, developer tools, file and browser operations — over a single uniform HTTP contract, so integrating the tenth API costs no more than the first.
What it is not: not a workflow or orchestration engine, not an LLM provider, and not a local scraping library. Each call is one hosted operation on
api.upapi.io; chaining calls is up to your code or your agent.Canonical URL: https://upapi.io · Docs: https://upapi.io/docs · Agent index: https://upapi.io/llms.txt
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 by asking your agent to run create_api_key over the hosted connection, or on the API keys page, 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 asdeclare 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 injectedexternal_*functions). Batch several operations into one round trip withPromise.allinstead of one tool call each. Killed after 30 seconds. A program that computes for more than 1.5 seconds without awaiting anexternal_*call, or for more than 5 seconds in total across all such stretches, is stopped withCPU_BUDGET_EXCEEDED: ..., because the sandbox shares the Node event loop with every other request the process serves. Needsquickjs-emscripten0.31.0(the exact version@mastra/quickjs0.1.1 resolves) installed next to it. Both are loaded on the firstexecute_typescriptcall, so a server that never runs one (or uses thefullsurface) 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.
Related
@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 MCP 질문
upAPI MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp -- npx -y @upapi/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
upAPI MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
upAPI MCP는 어떤 도구를 제공하나요?
2개 도구를 제공합니다. 예: search_ops, call_op.
MCP를 통해 upAPI에 어떻게 연결하나요?
stdio를 통해 API key를 사용하여 로컬에서 연결하거나, OAuth 로그인을 지원하는 호스팅된 HTTP 엔드포인트를 사용할 수 있습니다.
서버에서 여러 작업을 동시에 실행할 수 있나요?
네, Code Mode를 사용하면 execute_typescript 도구를 통해 Promise.all을 사용하여 여러 작업을 한 번의 왕복으로 배치 처리할 수 있습니다.