upAPI

@upapi/mcp

upAPI (upapi.io) は API マーケットプレイス兼ゲートウェイです。1 つの API キーと共通のクォータで、カタログ内のあらゆる操作（ソーシャルメディア、検索、地図、金融、開発者ツール、ファイルやブラウザーの操作）を、統一された単一の HTTP コントラクト経由で呼び出せます。そのため、10 個目の API の統合にかかる手間は、最初の API と変わりません。

該当しないもの： ワークフローやオーケストレーションのエンジンではなく、LLM プロバイダーでも、ローカルのスクレイピングライブラリでもありません。各呼び出しは api.upapi.io 上のホスト型操作です。呼び出しを連結するのは、ご自身のコードまたはエージェントです。

正式な URL：https://upapi.io · ドキュメント：https://upapi.io/docs · エージェント向けインデックス： https://upapi.io/llms.txt

公開されているすべての upAPI 操作を MCP ツールとして利用できます。ウェブ検索、SERP、ソーシャルプロフィール、開発者ツールの検索、地理・金融データなどを、エージェントから直接呼び出せます。

接続方法は 2 種類あり、違いは呼び出しの認証方法だけです。

	ローカル（stdio）	ホスト型（HTTP）
エンドポイント	npx @upapi/mcp	https://app.upapi.io/api/mcp
認証	お使いの upapi_ API キー	upAPI アカウントでサインイン（OAuth）
実行場所	お使いのマシン	upAPI 上
最適な用途	スクリプト、CI、セルフホスト型エージェント	Claude、IDE、リモート MCP に対応するあらゆるもの

どちらも同じスキーマの同じツールを公開し、同じクォータを消費します。

ホスト型 — インストール不要

リモートサーバーに対応した MCP クライアントで、次のエンドポイントを指定してください。

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

ブラウザーで upAPI へのサインイン手順が案内されるため、コピーするキーはありません。Claude Code の場合：

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

ローカル — API キー

app.upapi.io → API Keys でキーを作成し、次のようにします。

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

Claude Desktop（claude_desktop_config.json）、Cursor、Windsurf では、同じ内容を JSON として設定します。

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

変数
UPAPI_API_KEY	必須	upapi_ キー
UPAPI_BASE_URL	任意	ゲートウェイのオリジン。既定値は https://api.upapi.io
UPAPI_TOOL_MODE	任意	compact（既定値）、directory、claude、full のいずれか — Tools を参照

キーはローカルでは検証されません。存在するかどうかだけを確認するため、キーがない場合は、ツール呼び出し時に原因不明の 401 として後から表面化するのではなく、読みやすいメッセージですぐに失敗します。キーが有効か、期限切れか、クォータ超過かは、すべてのマシンからの呼び出しについて回答する唯一の場所であるゲートウェイで判定されます。

ツール

ホスト型エンドポイントは、デフォルトでコンパクトなテーブルを提供します。メタツールが2つと、常時利用可能な操作がいくつかあり、合計で数キロバイトです。

ツール	機能
search_ops	意図に基づいて操作を検索します。スラッグ、説明、パラメーター、クォータコストを返します
call_op	スラッグを指定して操作を1つ実行します：{ "slug": "github-repo.get", "input": { … } }

ツールテーブルは毎ターン、コンテキストとして再送されます。そのため、操作ごとにツールを1つ用意すると、ターンごとに数十キロバイトの JSON Schema が必要になり、テーブルが大きくなってツール選択の精度が目に見えて低下します。search_ops と call_op の組み合わせなら、カタログが拡大してもサイズは一定です。web-search.post、github-repo.get、wikipedia-article.get はフルツールとしてテーブルに残るため、一般的なケースでは探索のための往復が不要です。

ほかに2つのテーブルがあります。?tools=full では、すべての操作がそれぞれ独自のツールになります。

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

?tools=directory では、主要な操作（ページから Markdown への変換、スクリーンショット、HTML から PDF への変換、PDF テキストの抽出、OCR、文字起こし、GitHub リポジトリ、npm パッケージ、Wikipedia、通貨）向けに、厳選された11個の名前付きツールが提供されます。読み取りツールと書き込みツールは分けて一覧表示され、call_op は含まれません。これは AI ディレクトリの審査基準が求める形式です（ターゲットパラメーターを受け取る汎用ディスパッチャーは不採用となり、スクレイピングしたソースを宣伝する一覧も不採用となります。そのため、Maps の3つの操作とウェブ検索は呼び出し可能なままですが、一覧には掲載されません）。また、Claude Desktop Extension に同梱されている形式でもあります。?tools=claude は、upAPI 自身が計算する8つの操作（ページから Markdown への変換、スクリーンショット、HTML から PDF への変換、PDF テキストの抽出、OCR、文字起こしとその結果、テキスト分析）を対象にした同じ形式で、Claude コネクターの一覧です。ローカルの stdio サーバーでは、UPAPI_TOOL_MODE に同じ名前を指定できます。デフォルトは compact で、ホスト型エンドポイントのデフォルトと同じ数キロバイトの形式です。full（UPAPI_TOOL_MODE=full）も引き続き利用可能です。これは、このサーバーが以前デフォルトとしていた「操作ごとにツールを1つ用意する」形式で設定済みのクライアント向けのロールバック手段です。

どのモードでも、まったく同じ操作を実行できます。モードによって変わるのは公開される内容であり、許可される内容ではありません。すべてのモードのすべてのツールには、readOnlyHint、destructiveHint、idempotentHint、openWorldHint が含まれます。これらはスラッグの動詞の接尾辞ではなく、ワーカーの動作に基づいて設定されます。操作名はスラッグ内の . と - を _ に置き換えたものです（web-search.post → web_search_post）。また、各ツールは操作の実際の JSON Schema（形式、範囲、デフォルト値、null 許容性）を公開します。このスキーマはワーカー自身のモデルから生成され、そのまま渡されます。

ホスト型サーバーは、どのモードでも公開カタログ全体にアクセスできます。2026-09-26 以降、非公開にされるカテゴリはありません。ローカル（stdio）サーバーと Desktop Extension は次回リリースで追いつく予定です。公開済みの 0.2.0 には63個の操作が含まれていますが、directory モードでは引き続き Social Media と Utility は非公開です。

directory モードで変わるのは、公開される内容だけです。公開一覧（Claude Desktop Extension など）に表示される、厳選された主要な操作セットです。

説明にはクォータコストが記載されるため、エージェントは使用量を管理できます。

ウェブを検索… upAPI 操作 web-search.post（Search）。呼び出しごとに月間クォータを25ユニット消費します。

失敗した操作は、isError: true と、upAPI の公開エラーコード（RATE_LIMITED、INVALID_INPUT、UPSTREAM_UNREACHABLE）で始まるテキストを含む通常のツール結果として返されます。レート制限の場合は、待機時間も秒単位で示されます。操作が失敗しても、セッションに影響はありません。

outputSchema は意図的に宣言していません。MCP では、これを宣言したサーバーに、対応する structuredContent の返却が求められますが、これらの出力はリアルタイムのサードパーティーのペイロードを記述するものです。予期しない null が1つあるだけで、成功した呼び出しがプロトコルエラーになってしまいます。

Mastra で使用する

ツールは、間に MCP トランスポートを挟まずに Mastra エージェントで直接動作します。@mastra/core と @mastra/mcp はオプションのピア依存関係です。ご自身でインストールし、バインディングは /mastra サブパスからインポートしてください。このパッケージ内のほかの部分は Mastra に一切触れません。そのため、 通常の npm i @upapi/mcp（および、それを基にビルドされるデスクトップ拡張機能のバンドル）を小さく保てます。

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! }),
  }),
});

エージェントにカタログの一部だけを表示する場合は、filter でテーブルを絞り込んでください。

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

createUpapiMcpServer — デフォルトで Code Mode

createUpapiMcpServer は、Mastra の MCPServer（@mastra/mcp。こちらもオプションのピア依存関係です）を構築します。その デフォルトのツール構成は Code Modeです。操作ごとに 1 つのツールを用意する代わりに、search_tools + execute_typescript を使います。99 件の操作を含む完全なカタログで測定したところ、tools/list は 111,016 bytes から 1,069 bytes に減少しました（99 個のツール → 2 個）。テーブルのサイズがカタログに応じて増加しなくなるためです。

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? }) は、この接続から呼び出せる操作を検索し、declare function external_<name>(...) 形式の TypeScript シグネチャとして返します。
• execute_typescript({ code }) は、分離された QuickJS サンドボックス内で短い TypeScript プログラムを実行します（@mastra/quickjs はもう 1 つのオプションのピア依存関係です。ネイティブバイナリは不要で、注入された external_* 関数以外のファイルシステム／ネットワーク／プロセスへのアクセスはありません）。操作ごとにツールを 1 回呼び出す代わりに、Promise.all を使って複数の操作を 1 回の往復でまとめて実行できます。30 秒後に終了します。external_* の呼び出しを待機せずに 1.5 秒を超えて計算を続けるプログラム、またはそのような処理の合計が 5 秒を超えるプログラムは、CPU_BUDGET_EXCEEDED: ... で停止されます。これは、サンドボックスが、プロセスが処理するほかのすべてのリクエストと Node イベントループを共有するためです。quickjs-emscripten の 0.31.0（@mastra/quickjs 0.1.1 が解決する正確なバージョン）を隣接してインストールする必要があります。どちらも最初の execute_typescript 呼び出し時に読み込まれるため、呼び出さないサーバー（または full 構成を使うサーバー）にはインストール不要です。

すべての external_* 呼び出しは、full 構成（以下を参照）が呼び出すものとまったく同じ createUpapiTools(options) ツールオブジェクトを解決先とします。別の認証経路はありません。拒否された操作呼び出しや失敗した操作呼び出しは、サンドボックス内で Error("<CODE>: <message>") としてスローされるため、ゲストプログラム独自の try／catch でコードを確認し、処理を分岐できます。操作の入力スキーマに適合しない引数も、同様に INVALID_INPUT: <details> をスローします。これは、サンドボックスの起動前に呼び出し自体が失敗する、不正な execute_typescript 入力とは別です。

公開する内容を変更するには、MCP_TOOL_SURFACE を設定するか、surface を渡してください。

値	公開する内容	使用する場面
codemode (default)	search_tools + execute_typescript	数行の TypeScript を記述できるすべてのモデル
full	操作ごとに 1 つのツール — 現在の createUpapiTools テーブル	ロールバック用、またはすでにこの構成に対応しているクライアント
both	2 つの構成の和集合	移行期間中に構成を試す、または一方から移行する場合

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 には、codemode ツールが含まれる場合（codemode と both）、Code Mode の仕様が自動的に含まれます。そうでなければ、モデルは search_tools／execute_typescript に対して TypeScript を記述するよう指示されません。

独自のサーバーを構築する

caller は、ツールテーブルで指定されていない唯一の項目です。これにより、同じツールを異なるトランスポートで実行できます。

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' });

Web 標準の Request／Response サーバー（Next.js のルート、Worker、Hono）では、/http サブパスからハンドラーをインポートしてください。app.upapi.io/api/mcp はこの方法で構築されています。

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 を使うと、ホスト独自の認可をテーブルに反映できます。upAPI では、これらをアクセストークンの ops:execute と ops:read スコープに対応付けています。どちらもデフォルトは true なので、スコープモデルを持たないホストには影響しません。

バンドル環境やファイルトレースを使うデプロイでは、パッケージのルートよりこのサブパスを優先してください。ここから読み込まれるのは MCP SDK のみですが、ルートエントリでは stdio サーバーも読み込まれます。どちらからも Mastra は読み込まれません。バインディングは @upapi/mcp/mastra の背後に配置されているため、Mastra エージェントを実行しないビルドで @mastra/core が読み込まれることはありません。

関連情報

• @upapi/sdk — 型付き HTTP クライアント、およびこのパッケージのツールテーブルの生成元となるオペレーションカタログ
• upapi.io/docs — オペレーションのリファレンス

開発について

このリポジトリは、公開されている @upapi/mcp の本拠地です。npm がインストールするパッケージであり、Issue やプルリクエストもこちらで受け付けています。ツールテーブルは @upapi/sdk のオペレーションカタログから派生しています。このカタログ自体は upAPI の非公開オペレーション定義から生成され、自動的に同期されるため、ツールの内容は上流で変更されます。これらのファイルにあるサーバー、ファサード、エラーマッピング、テストは手書きのコードであり、変更する対象です。