Octen MCP Server

The official Model Context Protocol server for Octen. It lets MCP-compatible assistants use Octen’s web tools directly inside their workflow:

search — search live web data with ranked results, highlights, filters, timestamps, and optional full content
news_search — search news results for current events, announcements, and timely reporting
extract — fetch known URLs as clean markdown or text, including page type and content category

Get API Key

Create a key from the API Platform.

GitHub

View source and contribute.

npm

Install the octen-mcp package.

Why Octen MCP

Octen MCP gives agents access to Octen’s live web data and clean page content without leaving the MCP client.

Realtime search

Search fresh web results for current events and fast-changing topics.

News search

Search headlines, announcements, and market updates from news-focused results.

Clean URL extraction

Turn web pages into clean, LLM-ready content for reading, summarization, and analysis.

Installation

You’ll need an Octen API key first. Create one from the API Platform.

Claude Desktop
Cursor
VS Code
Claude Code
Other clients

Add to claude_desktop_config.json:

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

Add to ~/.cursor/mcp.json:

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

Install at the user level:

Or add to .vscode/mcp.json:

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

claude mcp add --scope user octen \
  -e OCTEN_API_KEY=your-key-here \
  -- npx -y octen-mcp

Use the same npx -y octen-mcp command with OCTEN_API_KEY in your MCP client config.

Tools

Tool	Use for	Returns
`search`	Web search by query	Ranked pages with `title`, `url`, `highlight`, timestamps, and optional `full_content`
`news_search`	News search by query	Same as `search`, with `topic` fixed to `news`
`extract`	Reading known URLs	One result per URL with `status`, content or highlights, `category`, and `page_structure`

`search`

Use search for live web retrieval. It supports:

topic: general or news
count: 1-100 results
include_domains / exclude_domains
include_text / exclude_text
time_basis: auto, published, or crawled
time_range, start_time, and end_time
highlight snippets or optional full_content
include_images and include_videos

{
  "query": "latest AI agent benchmark results",
  "count": 5,
  "time_range": "week",
  "highlight": {
    "enable": true,
    "max_tokens": 400
  }
}

`news_search`

Use news_search for current events, headlines, announcements, and time-sensitive reporting. It uses Octen Search with topic set to news. Equivalent Search API request:

{
  "query": "Fed rate decision",
  "topic": "news",
  "count": 10,
  "time_basis": "published",
  "time_range": "day"
}

`extract`

Use extract when the input is one or more URLs. It supports:

urls: 1-20 URLs
query: return ranked highlights from each page instead of the full body
max_age_seconds: cache freshness control
format: markdown or text
include_images, include_videos, include_audio, and include_favicon

{
  "urls": [
    "https://docs.octen.ai/api-reference/search",
    "https://docs.octen.ai/api-reference/extract"
  ],
  "format": "markdown"
}

Response shapes

Search returns a query and ranked result list:

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest AI agent benchmark results",
    "results": [
      {
        "title": "Example result",
        "url": "https://example.com/article",
        "highlight": "Query-relevant snippet...",
        "time_published": "2026-06-20T00:00:00Z",
        "time_last_crawled": "2026-06-23T08:30:05Z"
      }
    ]
  },
  "meta": {
    "usage": { "num_search_queries": 1, "full_content_tokens": 0 },
    "latency": 237
  }
}

Extract returns one result per URL:

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "results": [
      {
        "url": "https://docs.octen.ai/api-reference/search",
        "status": "success",
        "title": "Search - Octen",
        "full_content": "Clean markdown or text content...",
        "time_last_crawled": "2026-04-21T08:30:05Z",
        "page_structure": { "primary": "Content Page", "secondary": "Article" },
        "category": { "primary": "Computers, Electronics & Technology", "secondary": "Artificial Intelligence" }
      }
    ]
  },
  "meta": {
    "usage": { "total_urls": 1, "successful_urls": 1 },
    "latency": 1832
  }
}

With extract.query, each successful URL returns highlights instead of full_content. Failed URLs return status: "failed" and an error_message; failed URLs are not billed.

Handling edge cases

Tool	Signal	Recommended handling
`search` / `news_search`	No results or weak highlights	Rewrite the query, adjust filters, widen the time window, or enable `full_content` for search results.
`extract`	`status: failed`	Read `error_message`; failed URLs are not billed.
`extract`	`page_structure.primary: "No Main Content"`	Treat it as a login wall, shell page, paywall, or page without useful main content.

Configuration

Variable	Required	Default
`OCTEN_API_KEY`	Yes	-
`OCTEN_API_URL`	No	`https://api.octen.ai`

Get API Key

GitHub

npm

​Why Octen MCP

Realtime search

News search

Clean URL extraction

​Installation

​Tools

​search

​news_search

​extract

​Response shapes

​Handling edge cases

​Configuration

Why Octen MCP

Installation

Tools

`search`

`news_search`

`extract`

Response shapes

Handling edge cases

Configuration