Sofya

sofya-mcp

Model Context Protocol 経由で公開される、AI エージェント向けの Web 検索、取得、抽出、詳細な調査を提供する Sofya 用 MCP サーバーです。

どちらの方法でも利用できます。

• ホスト型（インストール不要）： API キーを Bearer トークンとして指定し、クライアントを https://sofya.co/mcp に接続します。これは MCP レジストリに co.sofya/sofya として登録されているサーバーです。
• ローカル： この sofya-mcp パッケージを stdio 経由で実行します。Sofya REST API をラップする軽量なラッパーで、同じツールを利用できます。

4 つのツールはすべて読み取り専用です。対象となる GitHub アカウントには、毎月 2,000 クレジットが無料で付与されます。

ツール

ツール	機能	コスト
search	Web を検索し、ページの内容を抽出して取得します（スニペットのみではありません）。news トピック、ドメインフィルター、鮮度に対応し、オプションで AI が合成した answer も取得できます。	1～2 クレジット（include_answer を指定すると追加で 10）
fetch	最大 10 件の URL をクリーンな Markdown として取得します。PDF、DOCX、XLSX、PPTX、EPUB などにも対応します。	URL あたり 2 クレジット
extract	ページを取得し、AI を使用して特定の構造化情報を抽出します。	10 クレジット
research	質問をサブクエリに分解し、多数の情報源を並列で読み込み、出典付きレポートを合成します。	50 クレジット

ホスト型サーバー（VS Code / Copilot など）

sofya.co で API キーを取得し（キーは ay_live_... の形式です）、クライアントをホスト型エンドポイントに接続します。

VS Code / GitHub Copilot（.vscode/mcp.json）：

{
  "servers": {
    "sofya": {
      "type": "http",
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

Claude Code：

claude mcp add --transport http sofya https://sofya.co/mcp --header "Authorization: Bearer ay_live_..."

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "sofya": {
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

続いて、エージェントに「Node.js の最新 LTS リリースノートを検索して」「この PDF を取得して要約して」「EU AI Act がオープンウェイトモデルをどう扱うか調査して」のように依頼します。API ドキュメントの全文は sofya.co/docs をご覧ください。

ローカルサーバー（npm）

前提条件

• Node.js 18+
• Sofya API キー — sofya.co で取得してください（キーは ay_live_... の形式です）

クイックスタート

インストール不要で、npx を使って直接実行できます。

SOFYA_API_KEY=ay_live_... npx -y sofya-mcp

設定

Claude Code

claude mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp

Claude Desktop / Cursor / Windsurf / VS Code

MCP 設定に追加します（例：claude_desktop_config.json または .cursor/mcp.json）：

{
  "mcpServers": {
    "sofya": {
      "command": "npx",
      "args": ["-y", "sofya-mcp"],
      "env": {
        "SOFYA_API_KEY": "ay_live_..."
      }
    }
  }
}

Codex

Codex CLI で追加します。

codex mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp

または、~/.codex/config.toml を直接編集します。Codex では環境変数が、ネストされた [mcp_servers.<name>.env] テーブルに配置される点に注意してください。

[mcp_servers.sofya]
command = "npx"
args = ["-y", "sofya-mcp"]

[mcp_servers.sofya.env]
SOFYA_API_KEY = "ay_live_..."

続いて、Codex 内で /mcp を実行し、サーバーが接続されていることを確認します。

環境変数

変数	必須	デフォルト	説明
SOFYA_API_KEY	はい	-	Sofya API キー（ay_live_...）。
SOFYA_BASE_URL	いいえ	https://sofya.co	Sofya API のベース URL を上書きします。

CLI フラグ --api-key および --base-url は、環境変数より優先されます。 npx sofya-mcp --list-tools を実行するとツールのスキーマが表示され、--help を指定するとオプションが表示されます。

開発

git clone https://github.com/sofya-co/sofya-mcp.git
cd sofya-mcp
npm install          # also builds via the prepare script
npm run build        # compile TypeScript to build/
npm run watch        # recompile on change
npm run inspector    # debug with @modelcontextprotocol/inspector

サーバーは単一ファイル src/index.ts で構成されています。ツール定義は、Sofya のホスト型 MCP サーバーと完全に同じです（名前、パラメーター、デフォルト値が同一です）。

ライセンス

MIT — LICENSE をご覧ください。