Sofya

sofya-mcp

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

Use it either way:

• Hosted (no install): connect your client to https://mcp.sofya.co/mcp (streamable HTTP). Sign in with OAuth, or send your API key as a Bearer token. This is the server listed in the MCP registry as co.sofya/sofya.
• Local: build this repo and run it over stdio. It is a thin wrapper around the Sofya REST API with the four core tools.

Eligible GitHub accounts (a year or older) get free monthly credits; everyone else pays as they go.

Tools

search, fetch, extract, research and get_balance are read-only.

Hosted server (VS Code / Copilot and others)

Point your client at the hosted endpoint. Clients with OAuth support (Claude, VS Code, Cursor, Cline and others) only need the URL and will ask you to sign in. To use an API key instead, get one at sofya.co (keys look like sofya_live_...) and send it as a Bearer token:

VS Code / GitHub Copilot (.vscode/mcp.json):

{

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

Claude Code, as a plugin (signs in with OAuth; plugin files in plugins/sofya):

/plugin install sofya --marketplace sofya-co/sofya-mcp

Claude Code, with an API key:

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

Cursor (~/.cursor/mcp.json):

{

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

Cline:

cline mcp install sofya --transport http https://mcp.sofya.co/mcp

Or in cline_mcp_settings.json:

{

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

Then ask your agent things like "search for the latest Node.js LTS release notes", "fetch this PDF and summarize it", or "research how the EU AI Act treats open-weight models". Full API docs: sofya.co/docs.

Local server

Prerequisites

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

Build

git clone https://github.com/sofya-co/sofya-mcp.git

cd sofya-mcp npm install # also builds to build/index.js

Check it starts:

SOFYA_API_KEY=sofya_live_... node build/index.js

In the examples below, replace /path/to/sofya-mcp with the folder you cloned.

Configuration

Claude Code

claude mcp add sofya --env SOFYA_API_KEY=sofya_live_... -- node /path/to/sofya-mcp/build/index.js

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": "node", "args": ["/path/to/sofya-mcp/build/index.js"], "env": { "SOFYA_API_KEY": "sofya_live_..." } } } }

Codex

Add it with the Codex CLI:

codex mcp add sofya --env SOFYA_API_KEY=sofya_live_... -- node /path/to/sofya-mcp/build/index.js

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

[mcp_servers.sofya]

command = "node" args = ["/path/to/sofya-mcp/build/index.js"]

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

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

Environment variables

CLI flags --api-key and --base-url take precedence over the env vars. Run node build/index.js --list-tools to print the tool schemas, or --help for options.

Development

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.