octen-mcp
OfficialThis server gives an agent nine live web tools — search, news, business/company cards, places, URL prediction, multi-angle search, page extraction, and image/video search — so it can find, read, and filter web content without a browser.
search— one ranked web lookup with domain/text include-exclude filters, language, time window, highlights, full page content, and images.news_search— recent articles plussubjects(storylines with summaries and time spans) for current events.business_search— structured company/person cards (profile, financials, key people, career history, announcements) with ranked sources.place_search— real-world place cards (address, coordinates, phone, hours, open status, rating) around coordinates, a city, or a named area, with optional review excerpts and web pages.pulse_search— fast (~10ms) prediction of the URL a query means: docs, help centres, known sites;liteorstandardmode.broad_search— decomposes a question into up to 30 sub-queries, runs them concurrently, returns results grouped per sub-query (undeduplicated).extract— reads 1–20 URLs and returns clean markdown/text withcategory,page_structure, optional highlights, links, media, and astandard/advanced/automode for hard sites.image_search— finds images by text query, referenceimage_url, or base64image_data(exactly one).video_search— finds videos by text query, with time filters (Beta; per-account access).Agent-friendly extras — early page filtering (
page_structure= "No Main Content" flags login walls;categoryfilters off-topic pages), token-efficient highlights, and schema-enforced arguments with clear error causes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@octen-mcp Fetch octen.ai and summarize the main product features"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: search the live web with domain, text, language, and time filters.news_search: recent news, returned both as articles and as storylines — the coverage grouped into subjects, each with a summary and the span it covers.pulse_search: the URL a query most likely means, in about 10ms — official docs, help centres, a site you could almost name. No freshness, no filters.place_search: real-world places as structured cards — address, coordinates, phone, opening hours, rating — around a point you give it, or in an area the query names.business_search: a company or person, returned as a structured card — profile, financials, key people, career history, recent announcements — alongside the sources behind it.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: 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 aboutpage_structure: what kind of page it ishighlights: ranked snippets when you pass aquery
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
Pricing
Octen bills per call by default: $1 per 1,000 web searches, and new accounts start with $5 in credit.
If your agent searches a lot, Search Plan is a flat monthly subscription with no overage fees:
Standard | Plus | |
Price | $20 / month | $100 / month |
Web Search ( | Unlimited | Unlimited |
Image Search ( | 1,000 / month | 5,000 / month |
Priority at peak times | – | ✓ |
What each tool costs on a plan:
Tool | On Search Plan |
| Included, unlimited |
| Included up to the monthly quota, then pay-as-you-go |
| Pay-as-you-go, billed per call |
Once you subscribe, every API key on your account uses the plan, including keys issued through OAuth sign-in.
Subscribe at octen.ai/pricing.
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 nine tools.
Endpoint | When | |
Hosted (recommended) |
| Nothing to install or update. Works with any client that speaks remote MCP. |
Local |
| 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 |
| The default. |
| Your client only offers one header field. |
| 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@octenOr 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 — clone this repository into Cursor's local plugin directory to get the hosted server and both skills in one step:
git clone https://github.com/Octen-Team/octen-mcp ~/.cursor/plugins/local/octenA Cursor Marketplace listing is pending review; this section will point at it
once it is live. To wire up only the server, add it to ~/.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 / Devin Desktop — ~/.config/devin/mcp_config.json on macOS and
Linux ($XDG_CONFIG_HOME/devin/ when that is set), %APPDATA%\devin\mcp_config.json
on Windows. Cascade accepts either serverUrl or url for a remote server;
~/.codeium/windsurf/mcp_config.json is the path for the legacy agent:
{
"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/mcpLeave 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-hereSigning 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.
Zed, Warp, Raycast, and Cline all connect to a remote server directly — point them at the endpoint and sign in. Raycast's HTTP transport offers an OAuth type of Dynamic, which is the one to pick: this server supports dynamic client registration, so there is no client ID to arrange.
{
"mcpServers": {
"octen": {
"url": "https://mcp.octen.ai/mcp"
}
}
}A client with no field for headers takes the key in the URL instead:
https://mcp.octen.ai/mcp?octenApiKey=your-key-here.
Only for a client that still cannot reach a remote server at all, the
mcp-remote bridge runs locally and forwards each request. 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"
]
}
}
}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,extractClients 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" }
}
}
}
Agent | One-line install |
Claude Code |
|
Codex |
|
Gemini CLI |
|
VS Code |
|
Cursor | Add to Cursor (then edit the key), or use the JSON above in |
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 insteadCursor:
~/.cursor/mcp.jsonVS Code workspace:
.vscode/mcp.json(useserversinstead ofmcpServers)Windsurf:
~/.codeium/windsurf/mcp_config.jsonGemini CLI:
~/.gemini/settings.jsonCline / other clients: paste it into that client's MCP settings
Troubleshooting
401 on every call. No credential reached the server, or the sign-in was
never completed. On a client that signs in, authorise the connection from its
MCP settings. On one that passes a key, 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. video_search is 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 the live web with domain, text, language (ISO 639-1), time, and content controls | a single focused web search |
| Recent news as ranked articles plus | current events and timely reporting |
| Company and person cards (profile, financials, key people, career, recent activity) plus the ranked sources | due diligence, competitor and executive lookup |
| Place cards (address, coordinates, phone, hours, status, rating) around a point or in a named area; web pages about them are opt-in | "near me", local lookup, opening hours, contact details |
| Predicted destinations — titles and URLs in ~10ms, or page content in | reaching known docs, help pages, a site you could name |
| Decompose a query into up to | research-style, multi-angle coverage |
| Fetch 1-20 URLs and return clean content, labels, and optional highlights | summarization, RAG, fact lookup |
| Search the web for images by text query (optional reference | finding pictures, photos, visual references |
| In Beta — contact us for beta access. Search the web for videos by text query | finding videos, clips, footage |
These nine 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 |
| string | yes | 1–500 chars | |
| integer | 1–100 |
| |
| array | ≤1200 items; each ≤60 | ||
| array | ≤1200 items; each ≤60 | ||
| array | ≤5 items; each ≤30 | ||
| array | ≤5 items; each ≤30 | ||
| string |
|
| |
| string |
| ||
| string | |||
| string | |||
| string |
|
| |
| string |
|
| |
| array |
| ||
| object |
| ||
| object |
| ||
| boolean |
| ||
| integer | 1–60 |
news_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| integer | 1–100 |
| |
| array | ≤1200 items; each ≤60 | ||
| array | ≤1200 items; each ≤60 | ||
| string |
|
| |
| string |
| ||
| string | |||
| string | |||
| array |
| ||
| object |
| ||
| object |
| ||
| object |
| ||
| integer | 1–60 |
/news-search is its own endpoint, so this is a different parameter set from
search: no include_text/exclude_text, format, safesearch or
include_images, and subjects on top. Omit subjects to take the API's
default (on, 2 storylines, 5 supporting articles each).
business_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| integer | 1–100 |
| |
| array | ≤1200 items; each ≤60 | ||
| array | ≤1200 items; each ≤60 | ||
| string |
|
| |
| string |
| ||
| string | |||
| string | |||
| array |
| ||
| object |
| ||
| object |
| ||
| object |
| ||
| integer | 1–60 |
The domain, time and language filters narrow the ranked results only — never
the entity cards. Omit entities to take the API's default (on, 2 entities,
5 activities and 5 news items each).
place_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| number | −90–90, WGS84; needs | ||
| number | −180–180, WGS84; needs | ||
| integer | 1–50000 m; needs both coordinates | ||
| object |
| ||
| object |
| ||
| object | see below | off | |
| integer | 1–60 |
web_search holds the filters the other search tools take top-level:
enable (default false), count 1–100, highlight, full_content,
include_domains, exclude_domains, language, time_basis, time_range,
start_time, end_time.
The places are the answer here and the pages cost context, which is why
web_search is off unless asked for. Pass a coordinate pair to get a
distance on every card; user_location is the fallback when only the city
is known, and returns no distances.
pulse_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| string |
|
| |
| integer | 1–10 |
| |
| string |
|
| |
| boolean | no effect in |
| |
| object |
| ||
| object |
| ||
| integer | 1–60 |
A destination predictor, not a search: one inference produces the URLs a query
most likely means. It takes none of search's domain, text, time or language
filters, sees no fresh content, and caps count at 10 rather than 100.
In lite the API returns URLs without a scheme; this server puts https://
back so the result can be passed straight to extract. standard adds
highlights, full content and images at roughly twice the latency.
broad_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| integer | 1–30 |
| |
| integer | 1–100 |
| |
| array | ≤1200 items; each ≤60 | ||
| array | ≤1200 items; each ≤60 | ||
| array | ≤5 items; each ≤30 | ||
| array | ≤5 items; each ≤30 | ||
| string |
|
| |
| string |
| ||
| string | |||
| string | |||
| string |
|
| |
| string |
|
| |
| array |
| ||
| object |
| ||
| object |
| ||
| boolean |
| ||
| integer | 1–300 |
extract
Parameter | Type | Required | Limits | Default |
| array | yes | ≤20 items; each ≤2048 | |
| string | ≤500 chars | ||
| integer | 300–31536000 |
| |
| string |
|
| |
| integer | 1–60 |
| |
| boolean |
| ||
| boolean |
| ||
| boolean |
| ||
| string |
| omitted (API uses | |
| object |
|
|
Choosing mode:
Scenario | mode |
News / blogs / docs / product pages (ordinary sites) |
|
Known hard sites (Reddit / X / LinkedIn / ResearchGate / anti-bot / SPA) |
|
Mixed batch, unsure which are hard |
|
Cost-sensitive, mostly ordinary sites |
|
Quality first, mostly hard sites |
|
standard can report success with empty or skeletal content on hard sites;
retry just those URLs with advanced. advanced is slower and 2.5x the price
of standard; auto bills each URL at the mode it used. With advanced or
auto, raise timeout (e.g. 60). Each result shows its resolved_mode, and
the meta line's billed: counts come from meta.usage.successful_by_mode,
which is authoritative for billing.
image_search
Parameter | Type | Required | Limits | Default |
| string | ≤500 chars | ||
| string | |||
| string | ≤5242880 chars | ||
| integer | 1–10 |
| |
| array | |||
| array | |||
| string |
|
| |
| integer | 1–60 |
video_search
Parameter | Type | Required | Limits | Default |
| string | yes | 1–500 chars | |
| integer | 1–10 |
| |
| string |
| ||
| string | |||
| string | |||
| string |
|
| |
| 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:
categoryhelps a pipeline ignore pages outside the target vertical before embedding or summarizing.Use less context:
queryreturnshighlightswhen 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 installEndpoints: 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 |
| yes | — | |
| no |
| |
| no | on | Set to |
| no | — | Honoured since 0.4.0. Node's built-in |
| no |
| 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 |
| no |
| Upper bound on the above when the origin advertises its own |
| no |
| Ceiling on establishing the outbound connection to |
| no | on | Set to |
| 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. |
| 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 |
| no |
|
|
| no | human text |
|
| no |
| Per-request body cap, in bytes, enforced on bytes received. Over it: |
| no |
| 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: |
| no |
| After a |
| no |
| On |
| no | — | Plugin-directory domain-verification token. When set, |
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 |
| for OAuth | — | Authorization server base URL. Compared byte-for-byte against the token's |
| for OAuth | — | This deployment's public URL, e.g. |
| for OAuth | — | Internal endpoint that exchanges a grant for an API key. Must be reachable privately; a public address will not serve it. |
| for OAuth | — | Shared secret sent to that endpoint as |
| no |
| How long a resolved grant is reused. This is the revocation-propagation window: a token revoked now keeps working for up to this long. |
| no |
| 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.logWindows:
%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=938msEach field answers a specific question:
call #N receivedtimestamp — when the call reached this process. Subtract it from the time your MCP client issued the tool call: the difference is time spent entirely outsideocten-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 FAILEDnames 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".elapsedvshandler_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 labelledrequest_idreads like one they could. Error messages carry only ids verified searchable on Octen's side — today that is exactly one: the server's ownrequest_idfrom 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 inspectMore 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
Available Tools
9 toolsbroad_searchBroad SearchARead-only
Search the web across many angles in one call — for comparisons, research, surveys, and questions with several distinct parts. Expands your question into multiple sub-queries and runs them concurrently.
USE WHEN the question has multiple distinct parts or entities that one search cannot cover:
comparing vendors / products / pricing across many sources
literature reviews, market or landscape surveys
open-ended "what are the options for X" / "how do people solve Y"
a question that clearly decomposes into 3+ independent sub-questions
multi-angle questions about recent events ("what shipped across the industry this month") — do NOT loop news_search
DO NOT USE for anything another tool answers directly — fanning out costs Nx and returns pages where those return the answer:
a single fact, entity, or document → use
searcha company or the people in one, including its financials → use
business_searchnews or recent events on a single topic → use
news_search(multi-angle is the exception above)a real-world place, address, opening hours → use
place_searchthe URL of a site or docs page you could almost name → use
pulse_searchimages or videos → use
image_search/video_searchre-running a disappointing search → do NOT call broad_search twice; follow up with a targeted
searchorextracton the specific gapsreading a page you already have the URL for → use
extracta straight A-vs-B comparison of two known entities → two targeted
searchcalls are cheaper and more controllable
COST: fans out into max_queries concurrent searches — roughly Nx the cost and notably higher latency than a single search. When in doubt, prefer search.
QUERY: pass one natural-language question (max 500 chars). Resolve pronouns and references from the conversation first — "how does it compare to the other one" is a useless query. Do NOT pre-split into sub-queries; that is this tool's job. For broader coverage raise max_queries rather than calling repeatedly. Per-sub-query options (count, language filter, domain / text filters, time window, highlight / full_content, media) match search and apply to every sub-query.
RESULTS are grouped per sub-query and NOT deduplicated — the same URL may appear under several sub-queries.
max_queries: 3-5 focused comparison (2-3 entities) | 5-10 multi-facet research | 10-20 landscape scan | 20-30 exhaustive survey
For a single focused lookup use search; to read a specific page use extract. Reach for this one only when no single tool above covers the question.
keywords: web search, search the web, look up, find information, research, compare, comparison, versus, alternatives, options, landscape, survey, market research, pricing, latest, current information, multi-part question
Inputs: query (required), count, format, timeout, +14 more.
business_searchBusiness SearchARead-only
Look up a company or a person and get a structured card back, plus the ranked sources behind it. A company card carries the profile, identifiers, financial and stock metrics, key people and recent announcements; a person card carries the current position, career history and recent activity. Name two companies in one query and you get a card for each, same fields, ready to compare. Set entities.enable to false for a plain ranked list instead.
USE FOR any question about a company or the people in one, including the numbers: revenue, net income, gross profit by quarter and year, share price and 52-week range, funding rounds and who led them, headcount and web traffic, key people and their titles, career history, recent announcements. Also "what does this company do", due diligence, and how two of them compare.
The card already holds those figures, so a question like "what was their revenue last quarter" is one call here. Reaching for search means reading a dozen pages for numbers this returns directly, and far more context for the same facts.
NOT FOR breaking coverage of an event — use news_search, which returns articles and storylines. NOT FOR general web pages — use search.
Examples: "NVIDIA company overview", "Lisa Su AMD CEO", "compare Stripe and Adyen payment processing", "semiconductor supply chain outlook".
keywords: company, business, due diligence, competitor, executive, CEO, founder, funding, valuation, revenue, earnings, stock, profile, who is, what does company do, compare companies
Inputs: query (required), count, timeout, end_time, +9 more.
extractURL ExtractARead-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.
Pick mode by how hard the URLs are: ordinary sites → standard (or omit), known hard sites → advanced, mixed/unsure → auto. If a standard result failed or came back empty/skeletal, retry just those URLs with mode "advanced".
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
Inputs: urls (required), mode, query, format, +6 more.
image_searchImage SearchARead-only
Find images on the web by text query OR by a reference image — returns ranked results (title, source page, dimensions, thumbnail, description, summary). Pass exactly one of: a text query, an image_url (a picture already on the web), or image_data (base64, for a picture you hold). Never more than one. Use this when the user wants pictures, photos, diagrams, screenshots, or visual references — not for general text web search.
keywords: find images, image search, photos, pictures, screenshots, visual reference, diagram, icon, illustration, reference image
Inputs: count, query, timeout, image_url, +4 more.
news_searchNews SearchARead-only
Search recent news and return ranked articles (title, url, snippet) — current events, headlines, timely reporting. Alongside the articles it returns subjects: the coverage grouped into storylines, each with a summary and the span it covers, so a "what happened with X" question is answerable without reading every article. Narrow with domain filters, a language filter (ISO 639-1 codes), and a time window (published/crawled start_time/end_time, or a relative time_range). include_domains/exclude_domains narrow the ranked articles only — the storylines are built from the open web either way. When the question restricts its sources ("what is Reuters saying about X"), answer from the articles, not the storylines. Pass highlight for a ranked snippet per article, or full_content for the cleaned article body (heavier — costs more context).
USE FOR what is being reported right now: breaking events, announcements, coverage of a company or person over the last days or weeks. For a company or person profile — financials, key people, career history — use business_search, which returns that as structured cards instead of articles to read. For non-news web pages use search. For a multi-angle question spanning several independent subtopics, use broad_search rather than looping this tool.
keywords: news search, latest news, headlines, current events, breaking news, recent, today, this week, press coverage, storylines
Inputs: query (required), count, timeout, end_time, +9 more.
place_searchPlace SearchARead-only
Find real-world places and get each one back as a card: name, category, address, coordinates, phone, website, opening hours, status (open / closed / permanently closed), rating and review count. Pass latitude and longitude to search around a point — each card then carries its distance in metres — and radius to cap how far. When you only know the city, pass user_location instead. A query that names its own area ("ramen in Shinjuku") works without either.
USE FOR anything with a location: "coffee shops near me", "family-friendly restaurants", "museums in Lisbon", "is this place open on Sunday", "what's their phone number". The cards answer these directly — search would return pages about places that then have to be read.
Set places.max_reviews (0-5) when what reviewers actually wrote is the question — "is it good for groups", "do people complain about the wait". Off by default: review text is long, and rating plus review_count already come on every card.
Set web_search.enable to true when the pages discussing these places matter too (round-ups, articles). It is off by default: the places are the answer here, and the pages cost context.
Pass the caller's location when the question is relative to them ("near me", "nearby", "closest") or names no area at all — without it such a query is not limited to anywhere, and "near me" means nothing. A query that names its own area does not need it, and sending coordinates there is data the search will not use.
keywords: places, near me, nearby, restaurant, cafe, coffee shop, bar, hotel, museum, shop, store, address, directions, opening hours, phone number, rating, reviews, local, map
Inputs: query (required), places, radius, timeout, +4 more.
pulse_searchPulse Search — find a site's URLARead-only
When what is wanted is a web address rather than what is written on the page, this is the tool. It returns up to 10 ranked candidate URLs with titles — the single most likely one, the top three, or a shortlist to choose from, whichever the question calls for. Official docs and API references ("github docs", "uv documentation", "python list methods"), help centres ("how do I return an amazon order"), a site you know exists ("youtube").
Prefer it over search for those: one inference predicts the URLs instead of searching and ranking them, so it answers in about 10ms for a fraction of the cost. Reaching for search to look up an address is slower and costs more for the same answer.
NOT FOR news or anything needing freshness — use news_search. NOT FOR a question that needs real retrieval across the open web, domain or language filters, or a time window — pulse has none of those parameters, sees no fresh content, and is not a cheaper substitute for search.
mode decides what comes back. lite (the default) returns titles and URLs only. standard adds highlights, full page content and images at roughly twice the latency; highlight, full_content and include_images do nothing in lite.
keywords: url lookup, find the site, official docs, api reference, documentation, help centre, homepage, where is, which url, candidate urls, top urls, quick lookup, destination, autocomplete
Inputs: query (required), mode, count, timeout, +4 more.
searchWeb SearchARead-only
Search the live web and return ranked results (title, url, snippet) — fast, fresh, real-time web search for one focused lookup. For news use news_search; for anything about a company or the people in one — what it does, who runs it, its revenue or share price, what it has announced — use business_search; when all you need is the URL of a site or docs page you could almost name, use pulse_search. Pass highlight to get a ranked snippet per result, or full_content to pull the cleaned page body inline (heavier — costs more context). Narrow with domain / text include-exclude filters, a language filter (ISO 639-1 codes), and a time window (published/crawled start_time/end_time, or a relative time_range). Set include_images to return image URLs per result.
USE FOR a single focused lookup that needs real retrieval and is not already covered by a tool above: one fact, one page, one document you do not already know the address of. If the question spans several independent subtopics, load and use broad_search instead — a sequence of search calls is slower and gives worse coverage than one fan-out. To read a page you already have the URL for, use extract.
keywords: web search, search the web, look up, find, check, fact, current information, latest, news, source, url, real-time
Inputs: query (required), count, format, timeout, +13 more.
video_searchVideo SearchARead-only
Find videos on the web by text query — returns ranked results (title, source page, cover image, duration, matching segment, authors, description). In Beta; contact us to request beta access. Pass a text query. Use this when the user wants to find videos, clips, footage, tutorials, or a specific moment within a video — not for general text web search.
keywords: find videos, video search, clips, footage, youtube, tutorial video, watch, movie, video clip
Inputs: query (required), count, timeout, end_time, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The tools are mostly distinct, and the descriptions explicitly define when to use each search variant. However, the search family still has some overlap — especially search vs. broad_search vs. pulse_search — where an agent could misselect based on question shape.
Names follow a consistent snake_case convention, with most tools using a clear [modifier]_search pattern. The bare `search` and verb-style `extract` are minor deviations but remain predictable.
Nine tools is well within the appropriate range for a multi-modal web research server. Each tool covers a distinct retrieval modality or strategy and earns its place.
The surface covers general, news, business, place, image, video, URL, and broad search plus page extraction, which is strong lifecycle coverage for web research. Minor gaps remain, such as no explicit crawling/pagination or deep structured follow-up tools.
Maintenance
Related MCP Connectors
Jina AI Reader/Search MCP — turn any URL into clean LLM-ready markdown, plus web search.
Clean Markdown and AI-readability scoring for any URL. Built for AI agents.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP server (stdio): fetch web pages as clean readable markdown via the AgentForge API
Related MCP Servers
- AlicenseAqualityBmaintenanceFetch URLs and return clean, LLM-ready markdown with metadata and layered prompt injection defense. Configurable timeouts, word limits, JS rendering, and link extraction. All-in-one MCP server + CLI.12MIT
- AlicenseAqualityDmaintenanceMCP server for Averra Extract — lets AI agents like Claude, Cursor, and ChatGPT convert any webpage into clean, LLM-ready Markdown.584 npmMIT
- AlicenseAqualityBmaintenanceWeb extraction MCP server for AI agents. Extract structured data from any URL with built-in Cloudflare bypass, JavaScript rendering, and intelligent parsing. Returns clean markdown or JSON.5794 npm2MIT
- AlicenseAqualityBmaintenanceMCP Server for Web2MD — convert webpage URLs to clean Markdown from Claude Desktop, Cursor, or any MCP-compatible agent.1213 npmMIT