octen-mcp

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, language, 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.

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, language (ISO 639-1), 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 (same per-sub-query options as search, including the language filter) | 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

Keep the tools always on (optional)

In clients with MCP tool search enabled (the Claude Code default), tools are deferred — the model runs a ToolSearch step to load them on demand. If you'd rather have the Octen tools resident from the first turn (no discovery step), set alwaysLoad on the server in your .mcp.json (Claude Code v2.1.121+):

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

Each always-loaded tool uses context on every turn, and alwaysLoad blocks startup until the server connects (capped at the ~5s connect timeout), so reserve it for tools you hit constantly. To keep the cost down, mark just the highest-traffic tools — e.g. search and broad_search — with "anthropic/alwaysLoad": true in each tool's _meta, leaving the rest deferred.

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.

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=<key> npm run inspect

More docs

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

License

MIT © Octen