English Français العربية

Sofya

Official registry Search and web

Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http sofya 'https://sofya.co/mcp' --header 'Authorization: <Bearer token. Use your Sofya API key prefixed with '\''Bearer '\'' (e.g. '\''Bearer ay_live_...'\''). Get one at https://sofya.co.>'
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "sofya": {
            "type": "http",
            "url": "https://sofya.co/mcp",
            "headers": {
                "Authorization": "<Bearer token. Use your Sofya API key prefixed with 'Bearer ' (e.g. 'Bearer ay_live_...'). Get one at https://sofya.co.>"
            }
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. sofya-mcp
  2. Tools
  3. Hosted server (VS Code / Copilot and others)
  4. Local server (npm)
  5. Development
  6. License

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://sofya.co/mcp with your API key as a Bearer token. This is the server listed in the MCP registry as co.sofya/sofya.
  • Local: run this sofya-mcp package over stdio. It is a thin wrapper around the Sofya REST API with the same tools.

All four tools are read-only. Eligible GitHub accounts get 2,000 free credits a month.

Tools

ToolWhat it doesCost
searchSearch the web and get extracted page content (not just snippets). Supports news topic, domain filters, freshness, and optional AI-synthesized answer.1-2 credits (+10 for include_answer)
fetchFetch up to 10 URLs as clean markdown. Also handles PDF, DOCX, XLSX, PPTX, EPUB, and more.2 credits / URL
extractFetch a page and pull specific structured info using AI.10 credits
researchDecompose a question into sub-queries, read many sources in parallel, and synthesize a cited report.50 credits

Hosted server (VS Code / Copilot and others)

Get an API key at sofya.co (keys look like ay_live_...), then point your client at the hosted endpoint.

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_..." }
    }
  }
}

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 (npm)

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.

Environment variables
VariableRequiredDefaultDescription
SOFYA_API_KEYyes-Your Sofya API key (ay_live_...).
SOFYA_BASE_URLnohttps://sofya.coOverride 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-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

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.

Frequently asked questions

What is Sofya?

Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.

How do I install Sofya?

It runs as a remote server. In Claude Code: claude mcp add --transport http sofya 'https://sofya.co/mcp' --header 'Authorization: <Bearer token. Use your Sofya API key prefixed with '\''Bearer '\'' (e.g. '\''Bearer ay_live_...'\''). Get one at https://sofya.co.>'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Sofya need an API key?

Yes. It expects Authorization, which you set in its configuration.

Is Sofya open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Sofya?

It is published by sofya-co. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.