sofya-mcp

MCP server for Sofya - web search, fetch, extract, and deep research for AI agents, exposed over the Model Context Protocol.

It runs locally over stdio and is a thin wrapper around the Sofya REST API. Bring your own Sofya API key.

Tools

Tool	What it does	Cost
`search`	Search the web and get extracted page content (not just snippets). Supports `news` topic, domain filters, freshness, and optional AI-synthesized `answer`.	1-3 credits (+5 for `include_answer`)
`fetch`	Fetch up to 10 URLs as clean markdown. Also handles PDF, DOCX, and more.	1 credit / URL
`extract`	Fetch a page and pull specific structured info using AI.	5 credits
`research`	Decompose a question into sub-queries, read many sources in parallel, and synthesize a cited report.	25 credits

Prerequisites

Node.js 18+
A Sofya API key - get one at sofya.co (keys look like ay_live_...)

Quick start

Run it directly with npx - no install needed:

bash

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

Configuration

Claude Code

Terminal

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

Claude Desktop / Cursor / Windsurf / VS Code

Add this to your MCP config (e.g. claude_desktop_config.json, or .cursor/mcp.json):

config.json

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

Codex

Add it with the Codex CLI:

bash

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

Or edit ~/.codex/config.toml directly. Note Codex puts environment variables in a nested [mcp_servers.<name>.env] table:

toml

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

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

Then run /mcp inside Codex to confirm the server is connected.

Already using Sofya's hosted MCP? Sofya also serves a remote MCP endpoint at https://sofya.co/mcp (Bearer auth, no install). Use this sofya-mcp package when you want a local stdio server launched by your client instead.

Environment variables

Variable	Required	Default	Description
`SOFYA_API_KEY`	yes	-	Your Sofya API key (`ay_live_...`).
`SOFYA_BASE_URL`	no	`https://sofya.co`	Override the Sofya API base URL.

CLI flags --api-key and --base-url take precedence over the env vars. Run npx sofya-mcp --list-tools to print the tool schemas, or --help for options.

Development

bash

git clone https://github.com/sofya-ai/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

The server is a single file, src/index.ts. Tool definitions mirror Sofya's hosted MCP server exactly (same names, parameters, and defaults).

License

MIT - see LICENSE.