sofya-mcp
OfficialThis server exposes tools for web search, URL fetching, AI-powered extraction, and deep research.
Search the web with extracted page content, news/general topics, freshness and domain filters, adjustable result count/depth, and an optional AI-synthesized answer.
Fetch URLs and return clean markdown for up to 10 pages at once, including PDFs, DOCX, and other document formats, with optional raw HTML.
Extract specific information from a webpage using an AI prompt, useful for structured data like pricing, specs, or contact details.
Run deep research that decomposes a question, reads multiple sources in parallel, and synthesizes a cited report.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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 asco.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
Tool | What it does | Cost |
| Search the web and get extracted page content (not just snippets). Supports | 1-2 credits (+2 for |
| Fetch up to 10 URLs as clean markdown. Also handles PDF, DOCX, XLSX, PPTX, EPUB, and more. | 1 credit / URL |
| Fetch a page and pull specific information from it using AI. | 10 credits |
| Decompose a question into sub-queries, read many sources in parallel, and synthesize a cited report. | 50 credits |
| Show the account's remaining credits. Hosted server only. | free |
| Return a payment link for a credit top-up. It does not charge anything. Hosted server only. | free |
search, fetch, extract, research and get_balance are read-only.
Related MCP server: mcp-web-search
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-mcpClaude 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/mcpOr 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.
Agent skills
Two skills in skills (the same files ship inside the Claude plugin at plugins/sofya/skills) teach an agent when and how to use Sofya: sofya-search (search, fetch, extract) and sofya-research (cited reports). They use the MCP tools when they are connected, and otherwise call the REST API with SOFYA_API_KEY. Install them into Claude Code, Cursor, Codex, Gemini CLI, Copilot and other agents with:
npx skills add sofya-co/sofya-mcpClaude Code plugin
The plugin bundles the hosted server and both skills:
/plugin marketplace add sofya-co/sofya-mcp
/plugin install sofya@sofyaCodex
The repo root is also a Codex plugin (.codex-plugin/plugin.json) with the hosted server and both skills.
Kiro
This repo is also a Kiro power (plugin.json, mcp.json and skills at the root). In Kiro, open Powers, choose Add Custom Power, then Import power from GitHub and enter https://github.com/sofya-co/sofya-mcp. Kiro opens a Sofya sign-in the first time a tool runs.
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.jsCheck it starts:
SOFYA_API_KEY=sofya_live_... node build/index.jsIn 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.jsClaude 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.jsOr edit ~/.codex/config.toml directly. Note Codex puts environment variables in
a nested [mcp_servers.<name>.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
Variable | Required | Default | Description |
| yes | - | Your Sofya API key ( |
| no |
| Override the Sofya API base URL. |
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/inspectorThe server is a single file, src/index.ts. Tool definitions
mirror Sofya's hosted MCP server exactly (same names, parameters, and defaults).
Privacy and support
The hosted server receives the tool arguments (queries, URLs, prompts) to answer each request and keeps them only in server logs, up to 30 days. Privacy policy · Terms
Support: support@sofya.co or sofya.co/contact.
License
MIT - see LICENSE.
Available Tools
4 toolsextractAInspect
Fetch a webpage and extract specific information using AI. Use this when you need structured data from a page (e.g. pricing, specs, contact info) rather than the raw content. Costs 5 credits.
Returns: content (the extracted text), url, credits_used, credits_remaining, usage (token counts).
Inputs: url (required), prompt (required).
fetchAInspect
Fetch one or more URLs and return their content as clean markdown. Use this to read articles, documentation, blog posts, or any page where you need the complete text, not just a snippet from search. Also supports PDF, DOCX, and other document formats. Costs 1 credit per URL. Max 10 URLs per request. Failed URLs are not charged.
Set include_raw_html=true to also get the raw HTML source in each result. Useful for inspecting embedded URLs, data attributes, iframes, or script tags that are stripped during markdown conversion. Returns null for non-HTML content (PDF, DOCX, etc.). Same cost.
Returns: results (array of {title, url, content, raw_html, published_time, success, error}), credits_used, credits_remaining.
Inputs: urls (required), include_raw_html.
researchAInspect
Perform comprehensive research on a topic. Decomposes your query into sub-queries, searches and reads multiple sources in parallel, then synthesizes a structured report with citations. Best for open-ended or comparative questions that need coverage from many angles. For simple factual lookups, use search instead (optionally with include_answer=true for cheap synthesis). Costs 25 credits.
Returns: query, report (structured markdown with citations), sources (array of {title, url, fetched}), sub_queries (the decomposed queries), credits_used, credits_remaining, usage (token counts).
Inputs: query (required), topic, freshness, max_sources.
searchAInspect
Search the web for current information on any topic. Returns extracted page content, not just snippets. Best for factual lookups, specific questions, or when you need a list of sources. For open-ended questions that need synthesis across many sources, use the research tool instead.
For news queries (current events, breaking news, politics, world events), set topic="news" to search news sources specifically. This returns recent articles with publication dates.
Set include_answer=true to get an AI-synthesized answer alongside results (adds 5 credits). This is the sweet spot for most agent tasks, e.g. basic + include_answer = 8 credits, much cheaper than a full 25-credit research call.
Returns: query, answer (if requested), results (array of {title, url, content, description, fetched, published_date}), search_depth, topic, elapsed_ms, credits_used, credits_remaining, altered_query.
Inputs: query (required), topic, freshness, max_results, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: extract for structured data from a single page, fetch for raw content, research for synthesized reports, and search for web searches. No overlap that would confuse an agent.
All tool names are single verbs (extract, fetch, research, search) following a consistent pattern. No mixed conventions or unclear naming.
Four tools is well-scoped for a server focused on web information retrieval and synthesis. Each tool earns its place without being too few or too many.
The tool set covers all major operations: fetching raw content, extracting structured data, searching the web, and performing deep research. No obvious gaps for the stated purpose.
Related MCP Connectors
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Web tools for AI agents: URL to clean Markdown, site crawl, screenshots, PDF/Office to text, OCR.
Web data for agents: YouTube transcripts, screenshots, Google News, WHOIS, jobs, tech stack, more.
Web knowledge fetching tools for your agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to perform web searches, extract webpage content, and conduct end-to-end search-and-extract operations using multiple search providers and content extraction methods.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search the web, read and extract content from webpages, fetch JSON from REST APIs, and collect links while bypassing anti-bot protections.35 npmISC
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to perform live web searches with ranked results and extracted page passages, plus clean markdown extraction of any URL.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to search the web across configured providers and crawl individual pages or entire sites into clean, deduplicated Markdown or JSON.-