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, by a reference image URL, or by base64 image data — exactly one of the three.
• 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 — or nothing at all, if your client signs in over OAuth (see Signing in instead).

Two ways to connect. Both serve the same six tools.

Node compatibility (local only): 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).

Connect to the hosted endpoint

Passing your key

Three ways, tried in this order. Prefer a header — a key in a URL is exposed to proxy logs, browser history and Referer headers.

Or use OAuth and paste no key at all — see Signing in instead.

By client

Claude Code — install the plugin. It brings the hosted server together with two skills, octen-web-search (routes a request to the right tool) and octen-research (multi-source research pipeline):

claude plugin marketplace add Octen-Team/octen-mcp
claude plugin install octen@octen

Or from inside a session: /plugin marketplace add Octen-Team/octen-mcp, then /plugin install octen@octen.

The plugin carries no credential. The first call is answered 401 and Claude Code walks you through the OAuth sign-in — run /mcp if you want to start it yourself. To register the server on its own instead, with a key:

claude mcp add --transport http octen https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "octen": {
      "url": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

VS Code — .vscode/mcp.json (workspace) or the user config. Note servers, not mcpServers, and the explicit type:

{
  "servers": {
    "octen": {
      "type": "http",
      "url": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Codex

codex mcp add octen --url https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"

Windsurf — ~/.codeium/windsurf/mcp_config.json. The key is serverUrl, not url:

{
  "mcpServers": {
    "octen": {
      "serverUrl": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Gemini CLI — ~/.gemini/settings.json. The key is httpUrl:

{
  "mcpServers": {
    "octen": {
      "httpUrl": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Claude Desktop takes the URL directly — no config file, no bridge. In Settings → Connectors, click Add custom connector, name it Octen, and enter:

https://mcp.octen.ai/mcp

Leave the Advanced settings empty: the OAuth Client ID and Secret fields are for servers that cannot register a client on their own, and ours can. Claude will offer to sign you in, and an Octen key is issued to that connection when you approve.

The connector dialog has no field for request headers, so an API key goes in the URL instead:

https://mcp.octen.ai/mcp?octenApiKey=your-key-here

Signing in is the better of the two — a URL is not a secret-carrying medium, and the sign-in flow can be revoked from your account without editing anything on this side. Note also that Claude connects from Anthropic's servers rather than from your machine, so a self-hosted deployment has to be reachable from the public internet for this to work at all; a private one wants the bridge below.

Clients that only speak stdio (Zed, Warp, Raycast, Cline) reach a remote server through the mcp-remote bridge. Note there is no space after the colon in --header — the value is split on the first one:

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.octen.ai/mcp",
        "--header", "x-api-key:your-key-here"
      ]
    }
  }
}

If a client cannot pass a header at all and takes only a URL, put the key in the URL instead: https://mcp.octen.ai/mcp?octenApiKey=your-key-here.

Signing in instead

If the deployment is configured with an authorization server — the hosted one is — a request with no credential is answered 401 + WWW-Authenticate: Bearer resource_metadata="…". That is the signal MCP clients use to start an OAuth flow, so a client that supports OAuth will offer to sign you in rather than ask for a key.

To move a connection that already has a key onto OAuth, point it at https://mcp.octen.ai/mcp/oauth (or append ?login). That path issues the challenge even when a key is present, which is the only way to trigger the switch — with a key attached, the ordinary endpoint has no reason to.

Loading fewer tools

?tools=search,extract limits a connection to the tools you name, for both tools/list and tools/call:

https://mcp.octen.ai/mcp?tools=search,extract

Clients load every advertised tool's full schema into the model's context, so narrowing the set is a real saving when you only need one or two. An unknown name is refused with a 400 listing the valid ones, rather than a connection that quietly comes up short.

Run it locally instead

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