Yapay zeka ajanlarının web kazıma, arama, sosyal medya sorgulama ve dosya işlemlerini tek bir birleşik API gateway üzerinden gerçekleştirmesini sağlar.
Ayrıca bilinen adı DevinoSolutions/upapi-mcp, upapi-mcp, @upapi/mcp
- Yıldızlar
- 0
- Araçlar
- 2
- İndirmeler, 30 gün
- —
- En son sürüm
- 0.2.0
- Son commit
- 13 Kas 2026
- Lisans
- MIT
upAPI MCP nedir?
Yapay zeka ajanlarının web kazıma, arama, sosyal medya sorgulama ve dosya işlemlerini tek bir birleşik API gateway üzerinden gerçekleştirmesini sağlar. 2 araç sunar; örneğin search_ops, call_op.
Özet, projenin README dosyasından oluşturuldu
upAPI MCP sunucusu hakkında
upAPI, yapay zeka ajanlarının çok çeşitli barındırılan işlemlere tek bir arayüz üzerinden erişmesine olanak tanıyan birleşik bir API gateway görevi görür. Geliştiriciler, düzinelerce ayrı servisi entegre etmek yerine; web araması, sosyal medya sorguları, finansal veriler, haritalar ve dosya işlemleri için araçlara erişmek amacıyla tek bir API anahtarı kullanabilirler. Bu yaklaşım, yeni yetenekler eklemenin entegrasyon karmaşıklığını artırmamasını sağlar.
Kullanıcılar, bir API anahtarı kullanarak yerel bir stdio kurulumuyla veya OAuth kullanarak barındırılan bir HTTP uç noktasıyla bağlantı kurabilirler. Sunucu, bağlam penceresi (context window) sınırlarını yönetmek için farklı araç modlarını destekler. Compact mode, şemayı küçük tutmak için arama ve çağırma araçlarını kullanırken; full mode her işlem için ayrı araçlar sunar. Claude Desktop, Cursor ve Windsurf gibi istemcilerle kullanılmak üzere veya doğrudan Mastra ajanlarına entegre edilmek üzere tasarlanmıştır.
Neler yapabilirsiniz
- 1Toplu işlemleri yürütmeBir geliştirici, zaman kazanmak için birden fazla API çağrısını tek bir gidiş-dönüş işleminde çalıştırmak üzere TypeScript kullanabilir.
- 2API kotalarını yönetmeBir ajan, aylık bütçe sınırları içerisinde kalmak için bir işlemin maliyetini kontrol edebilir.
- 3Web sayfalarından içerik çıkarmaBir ajan, bir web sayfasını Markdown formatına dönüştürebilir veya bir sitenin ekran görüntüsünü alabilir.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
upAPI MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleupAPI MCP'yi Claude Code içine yükleyin
$ claude mcp add --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp -- npx -y @upapi/mcpupAPI MCP'yi Cursor içine yükleyin
~/.cursor/mcp.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}upAPI MCP'yi VS Code içine yükleyin
.vscode/mcp.json
{
"servers": {
"upapi-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}upAPI MCP'yi VS Code CLI içine yükleyin
$ code --add-mcp '{"name":"upapi-mcp","type":"stdio","command":"npx","args":["-y","@upapi/mcp"],"env":{"UPAPI_API_KEY":"<YOUR_UPAPI_API_KEY>"}}'upAPI MCP'yi Claude Desktop içine yükleyin
claude_desktop_config.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}upAPI MCP'yi Codex içine yükleyin
$ codex mcp add upapi-mcp --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' -- npx -y @upapi/mcpupAPI MCP'yi Codex config.toml içine yükleyin
~/.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>"
upAPI MCP'yi Gemini CLI içine yükleyin
$ gemini mcp add -s user -e 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp npx -- -y @upapi/mcpupAPI MCP'yi Gemini settings.json içine yükleyin
~/.gemini/settings.json
{
"mcpServers": {
"upapi-mcp": {
"command": "npx",
"args": [
"-y",
"@upapi/mcp"
],
"env": {
"UPAPI_API_KEY": "<YOUR_UPAPI_API_KEY>"
}
}
}
}upAPI MCP araçları 2
README dosyasından algılandısearch_opscall_op
| search_ops | — | |
| call_op | — |
Yapılandırma
UPAPI_API_KEYGerekliGizliupAPI 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.
| Ad | Açıklama | Sunucu |
|---|---|---|
| UPAPI_API_KEY | upAPI API key (create one at https://app.upapi.io/dashboard/api-keys) | GerekliGizli |
| MCP_TOOL_SURFACE | — | |
| UPAPI_TOOL_MODE | Tool table: full (default), directory (curated named tools) or compact. |
Otomatik kontroller
Çalıştırıldı 12 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır
- Kaynak deposu bağlantılı ve erişilebilirGeçti
- Açık kaynak lisansı (OSI)Geçti
- Son bir yıl içinde commit veya sürüm mevcutGeçti
- Paket adı popüler bir pakete yakın değilGeçti
- Uzak uç nokta HTTPS kullanıyorGeçti
- Yıkıcı araçlar etiketlenmişGeçti
- Modele yönelik gizli talimat yokGeçti
- Pakette veya bağımlılıklarında kritik uyarı yokGeçti
@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 soruları
upAPI MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde claude mcp add --env 'UPAPI_API_KEY=<YOUR_UPAPI_API_KEY>' upapi-mcp -- npx -y @upapi/mcp komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
upAPI MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
upAPI MCP hangi araçları sunar?
2 araç sunar; bunlar arasında search_ops, call_op yer alır.
MCP aracılığıyla upAPI'ye nasıl bağlanabilirim?
stdio üzerinden bir API anahtarı kullanarak yerel olarak bağlanabilir veya OAuth girişini destekleyen barındırılan HTTP uç noktasını kullanabilirsiniz.
Sunucu aynı anda birden fazla işlem yapmayı destekliyor mu?
Evet, Code Mode kullanarak, Promise.all yardımıyla birkaç işlemi tek bir gidiş-dönüş işleminde toplamak için execute_typescript aracını kullanabilirsiniz.