Octen Mcp

octen-mcp

[](https://www.npmjs.com/package/octen-mcp) [](https://www.npmjs.com/package/octen-mcp) [](LICENSE) [](https://github.com/Octen-Team/octen-mcp/actions/workflows/ci.yml)

MCP server for Octen. Plug it into Claude, Cursor, VS Code, Windsurf, or any MCP client to give your agent live web search and URL extraction.

Core capabilities:

• search / news_search: search the live web with domain, text, and time filters.
• broad_search: decompose a query into multiple sub-queries, search them concurrently, and return results grouped per sub-query for broad coverage.
• extract: turn one or more URLs into clean, LLM-ready content.
• image_search (In Beta — contact us for beta access): search the web for images by text query, optionally with a reference image.
• video_search (In Beta — contact us for beta access): search the web for videos by text query.

What makes Octen useful for agents is that extract returns more than page text. Each successful result also includes:

• category: what the page is about
• page_structure: what kind of page it is
• highlights: ranked snippets when you pass a query

That lets an agent skip login walls, nav pages, and off-topic URLs before spending tokens on the full body.

Why Octen MCP

Fast

Web search averages 62ms. Fast enough for multi-step MCP workflows.

Accurate

Powered by SOTA text and VL embedding models. Better sources, fewer hallucinations.

Fresh

Live web data with minute-level updates. Useful for news, prices, and fast-moving pages.

Efficient

Clean highlights, optional full_content, and page labels keep model context relevant.

Quick start

You need an OCTEN_API_KEY from octen.ai.

[](https://vscode.dev/redirect/mcp/install?name=octen&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Octen%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22octen-mcp%22%5D%2C%22env%22%3A%7B%22OCTENAPIKEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=octen&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Octen%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22octen-mcp%22%5D%2C%22env%22%3A%7B%22OCTENAPIKEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders)

For most MCP clients, the config is:

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": {
        "OCTEN_API_KEY": "your-key-here"
      }
    }
  }
}

Install command by client

| Agent | One-line install | |--|--| | Claude Code | claude mcp add --scope user octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp | | Codex | codex mcp add octen --env OCTEN_API_KEY=your-key-here -- npx -y octen-mcp | | Gemini CLI | gemini mcp add octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp | | VS Code | code --add-mcp '{"name":"octen","command":"npx","args":["-y","octen-mcp"],"env":{"OCTEN_API_KEY":"your-key-here"}}' (or click a badge above) | | Cursor | Add to Cursor (then edit the key), or use the JSON above in ~/.cursor/mcp.json | | Claude Desktop | No CLI — add the JSON above to the config file (see below) |

Config file locations

For clients without a CLI installer, drop the JSON config above into:

• Claude Desktop: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json
• VS Code workspace: .vscode/mcp.json (use servers instead of mcpServers)
• Windsurf / Cline / other clients: paste it into that client's MCP settings

Tools

| Tool | What it does | Best for | |---|---|---| | search | Search the live web with domain, text, time, and content controls | a single focused web search | | news_search | Same engine as search, fixed to news | current events and timely reporting | | broad_search | Decompose a query into up to max_queries sub-queries, search concurrently, return grouped results | research-style, multi-angle coverage | | extract | Fetch 1-20 URLs and return clean content, labels, and optional highlights | summarization, RAG, fact lookup | | image_search | In Beta — contact us for beta access. Search the web for images by text query (optional reference image_url) | finding pictures, photos, visual references | | video_search | In Beta — contact us for beta access. Search the web for videos by text query | finding videos, clips, footage |

Reference docs:

• Search: docs.octen.ai/api-reference/search
• Extract: docs.octen.ai/api-reference/extract

Why agents like this

Most extract tools stop at "here is the page body." Octen helps one step earlier:

• Skip bad pages early: page_structure.primary == "No Main Content" tells the agent it hit a login wall, empty shell, or similar non-content page.
• Filter by topic early: category helps a pipeline ignore pages outside the target vertical before embedding or summarizing.
• Use less context: query returns highlights when the user wants a specific fact instead of the full page.

For the full decision tree and integration patterns, see [docs/best-practices.md](docs/best-practices.md).

Example prompts

• Fetch octen.ai and summarize the main product features.
• Search for recent MCP news from the last week.
• Fetch these URLs and only summarize the ones whose category is Finance.
• Search site:docs.anthropic.com prompt caching and return only the relevant highlights.

Environment variables

| Variable | Required | Default | |---|---|---| | OCTEN_API_KEY | yes | — | | OCTEN_API_URL | no | https://api.octen.ai |

Local development

git clone https://github.com/Octen-Team/octen-mcp.git
cd octen-mcp
npm install
npm run build
OCTEN_API_KEY= npm run inspect

More docs

• Best practices for agent integration: [docs/best-practices.md](docs/best-practices.md)
• Search API reference: docs.octen.ai/api-reference/search
• Extract API reference: docs.octen.ai/api-reference/extract

License

[MIT](LICENSE) © Octen

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Octen-Team
• Source: Octen-Team/octen-mcp
• License: MIT
• Homepage: https://docs.octen.ai/api-reference/extract

Install and usage instructions live in the source repository linked above.