Skip to main content
Glama
Octen-Team

octen-mcp

Official
by Octen-Team
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

octen-mcp

npm version npm downloads License: MIT CI

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.

Related MCP server: Averra Extract MCP

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.

Endpoint

When

Hosted (recommended)

https://mcp.octen.ai/mcp

Nothing to install or update. Works with any client that speaks remote MCP.

Local

npx -y octen-mcp

Clients without remote support, air-gapped setups, or when you want the process on your own machine.

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.

Form

Use when

x-api-key: <key>

The default.

Authorization: Bearer <key>

Your client only offers one header field.

?octenApiKey=<key> appended to the URL

Your client accepts nothing but a URL.

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" }
    }
  }
}

Install in VS Code Install in VS Code Insiders

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. For the hosted endpoint use Settings → Connectors → Add custom connector (above); for a local install, the config file (below)

Config file locations

  • Claude Desktop: ~/Library/Application\ Support/Claude/claude_desktop_config.json — only needed for a local (stdio) install; the hosted endpoint is added as a connector instead

  • Cursor: ~/.cursor/mcp.json

  • VS Code workspace: .vscode/mcp.json (use servers instead of mcpServers)

  • Windsurf: ~/.codeium/windsurf/mcp_config.json

  • Gemini CLI: ~/.gemini/settings.json

  • Cline / other clients: paste it into that client's MCP settings

Troubleshooting

401 on every call. No credential reached the server. Check the header name — x-api-key, or Authorization: Bearer — and, if you are using mcp-remote, that there is no space after the colon in --header.

The tools do not appear. Most clients read MCP config once at startup; restart the client after editing it. If the config uses the wrong key for your client (url vs serverUrl vs httpUrl), the server is never contacted at all — see the per-client sections above.

406 Not Acceptable. The request's Accept header must list both application/json and text/event-stream. Clients do this for you; hand-rolled curl probes usually do not, and the resulting 406 looks like an auth failure.

400 mentioning tools. A name in ?tools= is not one this deployment serves. The error lists the ones that are.

A tool errors with code=403 … beta access. image_search and video_search are in Beta and enabled per account; the message says how to request it.

Errors name what happened. A failed call reports which dependency failed and why — a timeout, a connection code, an expired token and by how long — plus Octen's own request_id where the API returned one. Quote that id in a support request; it is the one an engineer can look up.

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

These six are the whole surface, on purpose. Embeddings, chat completions, Answer and Research are Octen APIs that this server deliberately does not expose — reach them through the Python SDK or the CLI. A tool an agent can see is a tool it will try, so the roster stays the set that earns its place in a tool list.

Reference docs:

Parameters

Transcribed from the schemas each tool publishes — and those are enforced, so an out-of-contract value is refused before any call is made, with a message naming the field. The limits track the API reference; a test fails if the two drift apart.

image_search takes exactly one of query, image_url or image_data.

query must be non-empty: an empty string is refused by the schema, and a whitespace-only one by the handler. Neither reaches the API.

timeout means two different things. On search, news_search, broad_search, image_search and video_search it is this server's own HTTP deadline for the call — it is removed from the request body and never sent to the API. On extract it is the API's documented per-URL fetch budget (1-60s) and does travel in the body; the local deadline for an extract call is derived from it with headroom, so raising timeout raises both.

Overlapping include_domains and exclude_domains are passed through as given. The API currently answers a domain listed in both with a validation error; the published reference describes exclusion taking precedence. Until those agree, this server neither silently drops nor reorders your filters — you get the API's answer.

search

Parameter

Type

Required

Limits

Default

query

string

yes

1–500 chars

topic

string

general / news

"general"

count

integer

1–100

5

include_domains

array

≤1200 items; each ≤60

exclude_domains

array

≤1200 items; each ≤60

include_text

array

≤5 items; each ≤30

exclude_text

array

≤5 items; each ≤30

time_basis

string

auto / published / crawled

"auto"

time_range

string

day / week / month / year / d / w / m / y

start_time

string

end_time

string

format

string

text / markdown

"text"

safesearch

string

off / strict

"strict"

language

array

[]

highlight

object

enable, max_tokens

full_content

object

enable, max_tokens

include_images

boolean

false

timeout

integer

1–60

news_search

Parameter

Type

Required

Limits

Default

query

string

yes

1–500 chars

count

integer

1–100

5

include_domains

array

≤1200 items; each ≤60

exclude_domains

array

≤1200 items; each ≤60

include_text

array

≤5 items; each ≤30

exclude_text

array

≤5 items; each ≤30

time_basis

string

auto / published / crawled

"auto"

time_range

string

day / week / month / year / d / w / m / y

start_time

string

end_time

string

format

string

text / markdown

"text"

safesearch

string

off / strict

"strict"

language

array

[]

highlight

object

enable, max_tokens

full_content

object

enable, max_tokens

include_images

boolean

false

timeout

integer

1–60

broad_search

Parameter

Type

Required

Limits

Default

query

string

yes

1–500 chars

max_queries

integer

1–30

5

topic

string

general / news

"general"

count

integer

1–100

5

include_domains

array

≤1200 items; each ≤60

exclude_domains

array

≤1200 items; each ≤60

include_text

array

≤5 items; each ≤30

exclude_text

array

≤5 items; each ≤30

time_basis

string

auto / published / crawled

"auto"

time_range

string

day / week / month / year / d / w / m / y

start_time

string

end_time

string

format

string

text / markdown

"text"

safesearch

string

off / strict

"strict"

language

array

[]

highlight

object

enable, max_tokens

full_content

object

enable, max_tokens

include_images

boolean

false

timeout

integer

1–300

extract

Parameter

Type

Required

Limits

Default

urls

array

yes

≤20 items; each ≤2048

query

string

≤500 chars

max_age_seconds

integer

300–31536000

86400

format

string

markdown / text

"markdown"

timeout

integer

1–60

30

include_images

boolean

false

include_videos

boolean

false

include_audio

boolean

false

image_search

Parameter

Type

Required

Limits

Default

query

string

≤500 chars

image_url

string

image_data

string

≤5242880 chars

topic

string

general / design

"general"

count

integer

1–10

5

include_domains

array

exclude_domains

array

safesearch

string

off / strict

"strict"

html_snippet

object

enable, max_tokens

timeout

integer

1–60

video_search

Parameter

Type

Required

Limits

Default

query

string

yes

1–500 chars

count

integer

1–10

5

time_range

string

day / week / month / year / d / w / m / y

start_time

string

end_time

string

safesearch

string

off / strict

"strict"

timeout

integer

1–60

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.

Self-hosting the HTTP server

The hosted endpoint above runs this same code; you can run it yourself instead:

PORT=8080 npx -y -p octen-mcp octen-mcp-http   # or: octen-mcp-http after a global install

Endpoints: POST /mcp (stateless Streamable HTTP) and GET /healthz. Stateless by design — there is no session to lose, so scaling is a matter of running more copies behind a load balancer. Credentials travel per request and never come from the server's own environment: a request without one fails rather than quietly spending the host's key.

Authorization is off unless you configure it. Set both OCTEN_OAUTH_AUTHORIZATION_SERVER and OCTEN_MCP_RESOURCE and the server advertises RFC 9728 protected-resource metadata and answers uncredentialed requests with a 401 challenge. Leave them unset and it advertises nothing — an instance should never point clients at an authorization server it does not have — and a missing key surfaces at call time instead.

Argument validation. Each tool's declared inputSchema is enforced, not just advertised: types, ranges, string lengths, array sizes, enums, required parameters, and the property list itself. An out-of-contract call is refused with a message naming the field, before anything is sent to the API.

Sending an image as base64. image_search accepts image_data up to 5MB encoded, which travels inside the JSON-RPC body. OCTEN_MCP_MAX_BODY defaults to 6 MiB to make that work unconfigured; OCTEN_MCP_MAX_INFLIGHT_BODY (24 MiB) separately bounds what all in-flight bodies hold at once, since a per-request cap does nothing about many concurrent ones.

Environment variables

Variable

Required

Default

Notes

OCTEN_API_KEY

yes

—

OCTEN_API_URL

no

https://api.octen.ai

OCTEN_ENABLE_BETA_TOOLS

no

on

Set to false/0/off/no to hide the Beta image_search / video_search tools from discovery.

HTTPS_PROXY / HTTP_PROXY / NO_PROXY

no

—

Honoured since 0.4.0. Node's built-in fetch ignores these by default, so before 0.4.0 the server could not reach the API from behind a proxy even when every other tool on the machine could. Set them explicitly in your client config — see below; most MCP clients do not pass your shell environment through.

OCTEN_KEEP_ALIVE_MS

no

60000

How long an idle connection is kept for reuse. undici's own default of 4s meant nearly every call re-paid a full TLS handshake (~515ms measured). 60s is measured against api.octen.ai, which closes idle connections between 60s and 90s — staying under that means we always release first, instead of dispatching onto a socket the origin has already closed. Re-measure if you point OCTEN_API_URL elsewhere.

OCTEN_KEEP_ALIVE_MAX_MS

no

600000

Upper bound on the above when the origin advertises its own Keep-Alive hint. api.octen.ai does not send one.

OCTEN_CONNECT_TIMEOUT_MS

no

10000

Ceiling on establishing the outbound connection to api.octen.ai — unrelated to the MCP client's own startup connect timeout mentioned above. Lower it (e.g. 5000) on a path where connections fail intermittently, so the automatic retry engages sooner.

OCTEN_RETRY

no

on

Set to false/0/off/no to disable the single automatic retry on connection-level failures. Retries cost quota when the original request had in fact reached the server.

OCTEN_HTTP2

no

off

Opt into HTTP/2. Measured no faster for the usual one-request-at-a-time pattern, and not reliable through every CONNECT proxy — worth trying if you issue many tool calls in parallel.

OCTEN_MCP_DEBUG

no

off

Request tracing on stderr (stdout carries MCP framing). See below.

Remote HTTP form only

These are read only by octen-mcp-http; the stdio entry ignores them.

Variable

Required

Default

Notes

PORT

no

8080

0 picks an ephemeral port.

OCTEN_MCP_LOG

no

human text

json emits one JSON object per event, for a log pipeline.

OCTEN_MCP_MAX_BODY

no

6291456

Per-request body cap, in bytes, enforced on bytes received. Over it: 413. Sized so image_search's image_data (5MB encoded) works unconfigured; turn it down if this deployment never sends images.

OCTEN_MCP_MAX_INFLIGHT_BODY

no

25165824

Ceiling on the total bytes all in-flight bodies hold at once. The per-request cap stops one huge request; this stops many ordinary ones. Over it: 503 + Retry-After. Measured: resident cost runs about ten times this, because a base64 body exists two or three times over as a UTF-16 string.

OCTEN_MCP_BODY_DRAIN_MS

no

2000

After a 413, how long to keep discarding the rest of the body so the 413 itself gets delivered.

OCTEN_DRAIN_TIMEOUT_MS

no

310000

On SIGTERM, how long in-flight calls may finish. Must stay below the pod's terminationGracePeriodSeconds, and above the longest tool budget (broad_search, 300s).

OCTEN_APPS_CHALLENGE_TOKEN

no

—

Plugin-directory domain-verification token. When set, GET /.well-known/openai-apps-challenge serves exactly this value as plain text (the body must be the token alone); unset, the path answers 404. Anonymous by design, like the PRM: the token is generated by the directory for its own verifier to read, not a secret of this deployment.

OAuth. Off unless both of the first two are set, so an instance never advertises an authorization server it does not have.

Variable

Required

Default

Notes

OCTEN_OAUTH_AUTHORIZATION_SERVER

for OAuth

—

Authorization server base URL. Compared byte-for-byte against the token's iss, and used to build the JWKS URL — no trailing slash; the process refuses to start with one, because it would reject every token.

OCTEN_MCP_RESOURCE

for OAuth

—

This deployment's public URL, e.g. https://mcp.example.com/mcp. Compared byte-for-byte against the token's aud (RFC 8707), so a stray trailing slash fails every call. Cannot be inferred behind a proxy, hence explicit.

OCTEN_OAUTH_RESOLVE_URL

for OAuth

—

Internal endpoint that exchanges a grant for an API key. Must be reachable privately; a public address will not serve it.

OCTEN_OAUTH_RESOLVE_TOKEN

for OAuth

—

Shared secret sent to that endpoint as X-Octen-Service-Token.

OCTEN_OAUTH_RESOLVE_CACHE_TTL_MS

no

60000

How long a resolved grant is reused. This is the revocation-propagation window: a token revoked now keeps working for up to this long. 0 resolves on every call, at the cost of putting that service in front of every tool call.

OCTEN_JWKS_REFETCH_COOLDOWN_MS

no

10000

Floor between JWKS refetches triggered by an unknown key id. The trigger is an unverified token header, so without a floor each such request becomes one request to the authorization server. Lowering it widens that by the same ratio.

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

License

MIT © Octen

Available Tools

6 tools
extractA
Read-only

Read one or more web pages by URL and return clean, LLM-ready content (markdown or text). By default (no query) it returns each page's full content — this is what you want in almost all cases. Only pass query when the user explicitly asks to fetch relevance-ranked snippets for a specific topic; doing so returns highlights INSTEAD of the full body, so the content will be partial. Every result also includes a category (topical) and page_structure (typology) classification. Bare hosts like 'octen.ai' are auto-normalized to https. Cached when fresh.

Use this when you already have the URL(s). To find pages first, use search or broad_search.

keywords: read page, fetch url, scrape, page content, article text, parse webpage, extract, read article, url content, open link

ParametersJSON Schema
NameRequiredDescriptionDefault
urlsYesURLs to extract. 1-20 per call, each ≤2048 chars. Bare hosts ok.
queryNoOptional — leave UNSET in the normal case. When unset, each result returns the page's `full_content` (the complete text). Only set this when the user explicitly wants relevance-ranked snippets for a specific query/topic: setting it makes each result return `highlights` (ranked excerpts) and OMIT `full_content`, so the page body will be incomplete. Do not pass it just to focus a normal fetch.
formatNoOutput format. Default markdown.markdown
timeoutNoPer-URL timeout in seconds (1-60).
include_audioNoReturn audio URLs found on each page.
include_imagesNoReturn image resources found on each page (also enables `cover_image` when the page has one).
include_videosNoReturn video URLs found on each page.
max_age_secondsNoMaximum age of cached content in seconds. Default 24h. Lower this for time-sensitive pages (news / prices).

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it read-only, open-world, and non-destructive, and the description adds meaningful behavioral details: query mode returns highlights instead of full body, bare hosts are auto-normalized to https, content is cached when fresh, and results include category and page_structure classifications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and default behavior, then the critical query warning, then routing guidance. Each sentence contributes a distinct fact; the keyword list is slightly redundant but aids discoverability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately conveys the return shape by mentioning full_content, highlights, category, and page_structure. It also covers caching, URL handling, and sibling alternatives, giving an agent enough context to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds useful operational semantics beyond the schema, especially the query/full-content trade-off and bare-host normalization, though some parameter guidance duplicates the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Read one or more web pages by URL and return clean, LLM-ready content (markdown or text).' It also distinguishes itself from search siblings by saying 'Use this when you already have the URL(s).'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool and when not to: 'Use this when you already have the URL(s). To find pages first, use search or broad_search.' It also specifies the only condition for passing query and warns that doing so returns partial content.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.5.2
    • Changedbroad_search2 fields changed
      • changedInput schema / properties / query / description
        Previous value: -"Search query. Max 500 chars."New value: +"Non-empty search query. Max 500 chars."
      • addedInput schema / properties / query / minLength
        Added value: +1
    • Changednews_search2 fields changed
      • changedInput schema / properties / query / description
        Previous value: -"Search query. Max 500 chars."New value: +"Non-empty search query. Max 500 chars."
      • addedInput schema / properties / query / minLength
        Added value: +1
    • Changedsearch2 fields changed
      • changedInput schema / properties / query / description
        Previous value: -"Search query. Max 500 chars."New value: +"Non-empty search query. Max 500 chars."
      • addedInput schema / properties / query / minLength
        Added value: +1
  2. 5 tool updatesv0.5.0
    • Changedbroad_search7 fields changed
      • changedInput schema / properties / exclude_domains / description
        Previous value: -"Drop results from these domains. Max 150, each ≤30 chars."New value: +"Drop results from these domains. Max 1200, each ≤60 chars."
      • changedInput schema / properties / exclude_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / exclude_domains / maxItems
        Previous value: -150New value: +1200
      • changedInput schema / properties / include_domains / description
        Previous value: -"Only return results from these domains (e.g. 'arxiv.org'). Max 1000, each ≤30 chars."New value: +"Only return results from these domains (e.g. 'arxiv.org'). Max 1200, each ≤60 chars."
      • changedInput schema / properties / include_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / include_domains / maxItems
        Previous value: -1000New value: +1200
      • removedInput schema / properties / include_videos
        Removed value: -{
-  "default": false,
-  "description": "Return video URLs found on each result page.",
-  "type": "boolean"
-}
    • Changedextract3 fields changed
      • addedInput schema / properties / max_age_seconds / maximum
        Added value: +31536000
      • changedInput schema / properties / urls / description
        Previous value: -"URLs to extract. 1-20 per call. Bare hosts ok."New value: +"URLs to extract. 1-20 per call, each ≤2048 chars. Bare hosts ok."
      • addedInput schema / properties / urls / items / maxLength
        Added value: +2048
    • Changedimage_search9 fields changed
      • removedInput schema / properties / end_time
        Removed value: -{
-  "description": "Upper bound for the time window, ISO 8601.",
-  "type": "string"
-}
      • changedInput schema / properties / html_snippet / properties / max_tokens / description
        Previous value: -"Max tokens per HTML snippet (min 100). Default 5000."New value: +"Max tokens per HTML snippet (100-100000). Default 5000."
      • addedInput schema / properties / html_snippet / properties / max_tokens / maximum
        Added value: +100000
      • addedInput schema / properties / image_data
        Added value: +{
+  "description": "Base64-encoded image to search by visual similarity, for an image you hold rather than one already on the web. At most 5MB encoded; JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS or SGI. A `data:` URI is accepted — its payload is used. Exactly one of `query`, `image_url` or `image_data` — never more than one.",
+  "maxLength": 5242880,
+  "type": "string"
+}
      • changedInput schema / properties / image_url / description
        Previous value: -"Optional public image URL to search by reference image (visual similarity), in addition to the text `query`."New value: +"Public image URL to search by visual similarity. Exactly one of `query`, `image_url` or `image_data` — never more than one."
      • changedInput schema / properties / query / description
        Previous value: -"Text query describing the images to find."New value: +"Text query describing the images to find. Exactly one of `query`, `image_url` or `image_data` — never more than one."
      • removedInput schema / properties / start_time
        Removed value: -{
-  "description": "Lower bound for the time window, ISO 8601 (e.g. '2025-01-01T00:00:00Z').",
-  "type": "string"
-}
      • removedInput schema / properties / time_range
        Removed value: -{
-  "description": "Relative time window (e.g. `week`, `month`). Mutually exclusive with `start_time`/`end_time` — if both are given, the absolute range wins.",
-  "enum": [
-    "day",
-    "week",
-    "month",
-    "year",
-    "d",
-    "w",
-    "m",
-    "y"
-  ],
-  "type": "string"
-}
      • removedInput schema / required
        Removed value: -[
-  "query"
-]
    • Changednews_search7 fields changed
      • changedInput schema / properties / exclude_domains / description
        Previous value: -"Drop results from these domains. Max 150, each ≤30 chars."New value: +"Drop results from these domains. Max 1200, each ≤60 chars."
      • changedInput schema / properties / exclude_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / exclude_domains / maxItems
        Previous value: -150New value: +1200
      • changedInput schema / properties / include_domains / description
        Previous value: -"Only return results from these domains (e.g. 'arxiv.org'). Max 1000, each ≤30 chars."New value: +"Only return results from these domains (e.g. 'arxiv.org'). Max 1200, each ≤60 chars."
      • changedInput schema / properties / include_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / include_domains / maxItems
        Previous value: -1000New value: +1200
      • removedInput schema / properties / include_videos
        Removed value: -{
-  "default": false,
-  "description": "Return video URLs found on each result page.",
-  "type": "boolean"
-}
    • Changedsearch7 fields changed
      • changedInput schema / properties / exclude_domains / description
        Previous value: -"Drop results from these domains. Max 150, each ≤30 chars."New value: +"Drop results from these domains. Max 1200, each ≤60 chars."
      • changedInput schema / properties / exclude_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / exclude_domains / maxItems
        Previous value: -150New value: +1200
      • changedInput schema / properties / include_domains / description
        Previous value: -"Only return results from these domains (e.g. 'arxiv.org'). Max 1000, each ≤30 chars."New value: +"Only return results from these domains (e.g. 'arxiv.org'). Max 1200, each ≤60 chars."
      • changedInput schema / properties / include_domains / items / maxLength
        Previous value: -30New value: +60
      • changedInput schema / properties / include_domains / maxItems
        Previous value: -1000New value: +1200
      • removedInput schema / properties / include_videos
        Removed value: -{
-  "default": false,
-  "description": "Return video URLs found on each result page.",
-  "type": "boolean"
-}
  3. 5 tool updatesv0.4.2
    • Changedbroad_search2 fields changed
      • changedInput schema / properties / timeout / description
        Previous value: -"Request timeout in seconds (1-60)."New value: +"Request timeout in seconds (1-300). Defaults to 120s if unset. Raise it for large `max_queries` surveys, which legitimately take longer."
      • changedInput schema / properties / timeout / maximum
        Previous value: -60New value: +300
    • Changedimage_search1 field changed
      • changedInput schema / properties / timeout / description
        Previous value: -"Request timeout in seconds (1-60)."New value: +"Request timeout in seconds (1-60). Defaults to 30s if unset."
    • Changednews_search1 field changed
      • changedInput schema / properties / timeout / description
        Previous value: -"Request timeout in seconds (1-60)."New value: +"Request timeout in seconds (1-60). Defaults to 30s if unset."
    • Changedsearch1 field changed
      • changedInput schema / properties / timeout / description
        Previous value: -"Request timeout in seconds (1-60)."New value: +"Request timeout in seconds (1-60). Defaults to 30s if unset."
    • Changedvideo_search1 field changed
      • changedInput schema / properties / timeout / description
        Previous value: -"Request timeout in seconds (1-60)."New value: +"Request timeout in seconds (1-60). Defaults to 30s if unset."
  4. 2 tool updatesv0.3.6
    • Addednews_search
    • Addedsearch
  5. 3 tool updatesv0.3.5
    • Changedbroad_search1 field changed
      • addedInput schema / properties / language
        Added value: +{
+  "default": [],
+  "description": "Languages to filter results by, as ISO 639-1 codes. Empty = no filter.",
+  "items": {
+    "enum": [
+      "ar",
+      "de",
+      "en",
+      "es",
+      "fr",
+      "hi",
+      "id",
+      "it",
+      "ja",
+      "ko",
+      "nl",
+      "pl",
+      "pt",
+      "ru",
+      "th",
+      "tr",
+      "vi",
+      "zh"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}
    • Removednews_search
    • Removedsearch
  6. 4 tool updatesv0.3.4
    • Changedbroad_search1 field changed
      • removedInput schema / properties / country
        Removed value: -{
-  "default": "auto",
-  "description": "Follow ISO 3166, the International Standard for country codes and codes for their subdivisions (e.g. `US`, `JP`); `auto` (default) determines it automatically.",
-  "type": "string"
-}
    • Addedextract
    • Changednews_search1 field changed
      • removedInput schema / properties / country
        Removed value: -{
-  "default": "auto",
-  "description": "Follow ISO 3166, the International Standard for country codes and codes for their subdivisions (e.g. `US`, `JP`); `auto` (default) determines it automatically.",
-  "type": "string"
-}
    • Addedsearch
  7. 4 tool updatesv0.3.3
    • Changedbroad_search1 field changed
      • addedInput schema / properties / country
        Added value: +{
+  "default": "auto",
+  "description": "Follow ISO 3166, the International Standard for country codes and codes for their subdivisions (e.g. `US`, `JP`); `auto` (default) determines it automatically.",
+  "type": "string"
+}
    • Removedextract
    • Changednews_search1 field changed
      • addedInput schema / properties / country
        Added value: +{
+  "default": "auto",
+  "description": "Follow ISO 3166, the International Standard for country codes and codes for their subdivisions (e.g. `US`, `JP`); `auto` (default) determines it automatically.",
+  "type": "string"
+}
    • Removedsearch
  8. 4 tool updatesv0.3.1
    • Addedbroad_search
    • Changedextract2 fields changed
      • removedInput schema / properties / include_favicon
        Removed value: -{
-  "default": false,
-  "description": "Return each page's favicon URL.",
-  "type": "boolean"
-}
      • changedInput schema / properties / include_images / description
        Previous value: -"Return image URLs found on each page."New value: +"Return image resources found on each page (also enables `cover_image` when the page has one)."
    • Addedimage_search
    • Addedvideo_search
  9. 3 tool updatesv0.2.2
    • Changedextract1 field changed
      • changedInput schema / properties / query / description
        Previous value: -"Optional intent-focused keywords. When set, each result returns `highlights` (most relevant snippets, ranked) instead of `full_content`."New value: +"Optional — leave UNSET in the normal case. When unset, each result returns the page's `full_content` (the complete text). Only set this when the user explicitly wants relevance-ranked snippets for a specific query/topic: setting it makes each result return `highlights` (ranked excerpts) and OMIT `full_content`, so the page body will be incomplete. Do not pass it just to focus a normal fetch."
    • Addednews_search
    • Addedsearch
  10. 1 tool updatev0.1.0
    • First observedextract
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 6 tools

Disambiguation4/5

Each tool targets a distinct retrieval modality (general search, fan-out research, news, page extraction, images, videos), and the descriptions draw explicit boundaries. The main ambiguity is that news_search is essentially search with topic=news, and broad_search can also operate in news mode, so the text-search tools could occasionally be confused.

Naming Consistency4/5

Most tools follow a predictable <modifier>_search pattern (broad_search, news_search, image_search, video_search), with search as the base. extract breaks the pattern and the bare search is a slight deviation, but all names are lowercase snake_case and clearly signal their function.

Tool Count5/5

Six tools is a well-scoped size for a web research server: each tool maps to a distinct retrieval task and none feels redundant or ornamental. This sits comfortably in the ideal range and avoids overwhelming an agent with overlapping capabilities.

Completeness5/5

The surface covers the full web-research workflow: finding pages via single or multi-angle search, filtering by news or media type, and extracting clean content from known URLs. There are no obvious dead ends, and the descriptions explicitly connect follow-up actions between search and extract.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers