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:

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

Configuration

Claude Code

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):

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

Codex

Add it with the Codex CLI:

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:

[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

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.