# sofya-co/sofya-mcp [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/sofya-co/sofya-mcp  
**GitHub Stars:** 1  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sofya-co-sofya-mcp

## Description
Web tools for AI agents through the Sofya API. Search the web for full page content instead of snippets, fetch URLs as clean markdown (including PDFs), extract structured data from a page with a prompt, and run multi-source deep research that returns a cited report.

## Tools
Capabilities this server exposes over MCP:

- **search** — Search the web and get extracted page content (not just snippets). Supports `news` topic, domain filters, freshness, and optional AI-synthesized `answer`.
- **fetch** — Fetch up to 10 URLs as clean markdown. Also handles PDF, DOCX, and more.
- **extract** — Fetch a page and pull specific structured info using AI.
- **research** — Decompose a question into sub-queries, read many sources in parallel, and synthesize a cited report.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `SOFYA_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What sofya-co/sofya-mcp MCP server does

sofya-co/sofya-mcp MCP server exposes four Sofya web capabilities through the Model Context Protocol: search, fetch, extract, and research. The tools are intended for agents that need to inspect source pages and documents, not just receive search-result snippets.

Search returns extracted page content and supports news-focused queries, domain restrictions, freshness settings, and an optional AI-generated answer. Fetch converts up to 10 supplied URLs into clean Markdown and can process formats such as PDF and DOCX. Extract combines page retrieval with an AI instruction to return targeted, structured information. Research breaks a question into smaller searches, reads multiple sources in parallel, and produces a report with citations.

## How it works

The package is a local stdio MCP server and acts as a thin client for the Sofya REST API. An MCP-compatible client starts the Node.js process, which uses the configured Sofya API key to make requests. The tool definitions match Sofya's hosted MCP interface, including tool names, parameters, and defaults.

Each operation consumes Sofya credits according to the README: search uses 1–3 credits, with 5 additional credits when an answer is requested; fetch uses 1 credit per URL; extract uses 5 credits; and research uses 25 credits. These costs are associated with the Sofya API rather than with the local process itself.

## Setup and configuration

Install is not required for a direct run. With Node.js 18 or newer and a Sofya API key, launch sofya-co/sofya-mcp MCP server with `SOFYA_API_KEY=ay_live_... npx -y sofya-mcp`. The key is required and uses the `ay_live_...` format shown in the project documentation.

For MCP clients, configure a stdio server whose command is `npx`, with `-y` and `sofya-mcp` as arguments. Pass `SOFYA_API_KEY` in the process environment. The README gives configurations for Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, and Codex. `SOFYA_BASE_URL` can optionally replace the default `https://sofya.co` API base URL. Command-line options for the API key and base URL take precedence over environment variables.

## Tools and capabilities

- `search`: Search the web with optional news topic, domain, freshness, and synthesized-answer settings.
- `fetch`: Retrieve as many as 10 URLs per request as Markdown, including supported PDF and DOCX content.
- `extract`: Ask the service to identify specific structured information from a page.
- `research`: Run decomposed, parallel source searches and return a cited synthesized report.

## Limitations and notes

The local package requires a Sofya API key and depends on the Sofya service for its web results and processing. API usage consumes credits, with research costing substantially more than individual search or fetch operations. The project requires Node.js 18 or later.

The package should not be confused with Sofya's hosted MCP endpoint at `https://sofya.co/mcp`. That endpoint uses Bearer authentication and does not require installing the local package; sofya-co/sofya-mcp MCP server is the option documented for local stdio execution. The README identifies the project license as MIT.

_Full upstream README: https://allmcps.com/mcp/sofya-co-sofya-mcp/readme_