Octen MCP Server

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.

Node compatibility: 0.4.2 and later run on every supported Node (>= 18.17), including Node 26+. Versions 0.4.1 and below fail every call on hosts whose embedded undici is v8+ (Node 26 and later) with Network error … code=UND_ERR_INVALID_ARG cause=invalid onError method — if you see that error, upgrade the package (or run on Node <= 24).

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

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

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

Setting these in Claude Desktop (and where the logs go)

MCP servers do not inherit your shell environment. Claude Desktop spawns them with HOME, LOGNAME, PATH, SHELL and USER — and nothing else except what you put in the server's env block. A proxy configured system-wide will not be picked up; it has to be named explicitly, alongside the API key:

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": {
        "OCTEN_API_KEY": "your-key-here",
        "HTTPS_PROXY": "http://proxy.example:8080"
      }
    }
  }
}

Restart Claude Desktop after editing the config — it reads it at launch.

Server output lands in:

• macOS: ~/Library/Logs/Claude/mcp-server-octen.log
• Windows: %APPDATA%\Claude\logs\mcp-server-octen.log

Everything the server writes to stderr, including the tracing below, goes there.

Diagnosing a slow or failing call

Add "OCTEN_MCP_DEBUG": "1" to the env block above while you are investigating, and take it out afterwards — the client appends this to a log file that is never rotated, so leaving it on grows that file for the life of the install.

With it on, every call is traced to stderr:

[octen-mcp 2026-08-14T04:36:36.219Z] call #1 received tool=search
[octen-mcp 2026-08-14T04:36:36.637Z] connect #1 established to api.octen.ai in 410ms peer=203.0.113.10:443 tls=TLSv1.3 alpn=http/1.1
[octen-mcp 2026-08-14T04:36:37.155Z] /search attempt=1 status=200 elapsed=935ms socket=new request_id=42cd56a5-…
[octen-mcp 2026-08-14T04:36:37.157Z] call #1 returning tool=search handler_total=938ms

Each field answers a specific question:

• call #N received timestamp — when the call reached this process. Subtract it from the time your MCP client issued the tool call: the difference is time spent entirely outside octen-mcp, in the host or in whatever relays between them. A client-side stopwatch alone cannot separate that from time we are responsible for.
• connect … established in Xms — a handshake happened, and what it cost. connect FAILED names the phase and error code instead.
• peer= / tls= / alpn= — which address the connection actually reached (the API hostname is anycast, so the hostname alone cannot tell you which edge), and the negotiated TLS version and protocol — a mismatch there otherwise presents as an unexplained slow or failed handshake.
• socket=new / socket=reused — whether this call paid for a handshake. This is the difference between "the service is slow" and "the connection was thrown away between calls".
• elapsed vs handler_total — time in the HTTP request vs time in the tool handler. A large gap means the cost is in request assembly or response formatting, not the network.
• request_id — in this trace only: the client-generated correlation id, stable across the retry, tying a call's attempts together. It never appears in user-facing error messages, deliberately: Octen support cannot look it up (the gateway does not record the header), and an id labelled request_id reads like one they could. Error messages carry only ids verified searchable on Octen's side — today that is exactly one: the server's own request_id from an API error envelope.

Failures name the cause rather than fetch failed:

Network error calling Octen Search: code=ECONNREFUSED cause=connect ECONNREFUSED 203.0.113.9:443
address=203.0.113.9:443 — could not establish a connection.
If this machine requires an HTTP proxy, set HTTPS_PROXY.

UND_ERR_CONNECT_TIMEOUT means the connection was never established, ECONNRESET means it was established and then torn down, and ENOTFOUND means DNS — three different problems with three different owners.

Request timeouts: search and the media tools default to 30s, broad_search to 120s (raisable to 300s), and extract to its per-URL budget plus headroom. The search tools accept a timeout parameter to override; extract's timeout is the server-side, per-URL fetch budget, so the client ceiling is derived from it rather than equal to it. The automatic retry draws down the same deadline as the first attempt, so the stated timeout bounds the whole call, retry included.

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