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

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

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.