> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Octen MCP Server
> Add the Octen MCP server to your client, hosted endpoint or local npx.
For AI agents: docs.octen.ai/integrations/octen-mcp-server.md
Lets MCP-compatible assistants use Octen directly inside their workflow:
* `broad_search` — decompose one question into concurrent sub-queries for broad, multi-angle coverage
* `search` — search live web data with ranked results, highlights, filters, and optional full content
* `image_search` — search the web for images by text or reference image
* `video_search` — search the web for videos by text query (beta)
* `extract` — fetch URLs as clean markdown or text
Create a key from the API Platform.
View source and contribute.
## Why Octen MCP
Web search averages 62ms. Fast enough for multi-step MCP workflows.
Powered by SOTA text and VL embedding models. Better sources, fewer hallucinations.
Live web data with minute-level updates. Useful for news, prices, and fast-moving pages.
Clean highlights, optional full\_content, and page labels keep model context relevant.
## Installation
You'll need an Octen API key first. Create one from the [API Platform](https://octen.ai/platform/api-keys).
Pick one of two ways to connect: the hosted endpoint, or running the server locally.
### Connect to the Hosted Endpoint
Point your client at `https://mcp.octen.ai/mcp` with your API key in an `x-api-key` header.
```bash theme={null}
claude mcp add --transport http octen https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"
```
In **Settings → Connectors**, click **Add custom connector**, name it `Octen`, and enter the URL `https://mcp.octen.ai/mcp`. Claude offers to sign you in, and a key is issued to that connection when you approve. No config file or bridge needed.
Add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"octen": {
"url": "https://mcp.octen.ai/mcp",
"headers": { "x-api-key": "your-key-here" }
}
}
}
```
Add to `.vscode/mcp.json`. Note `servers`, not `mcpServers`, and the explicit `type`:
```json theme={null}
{
"servers": {
"octen": {
"type": "http",
"url": "https://mcp.octen.ai/mcp",
"headers": { "x-api-key": "your-key-here" }
}
}
}
```
Add to `~/.codeium/windsurf/mcp_config.json`. The key is `serverUrl`, not `url`:
```json theme={null}
{
"mcpServers": {
"octen": {
"serverUrl": "https://mcp.octen.ai/mcp",
"headers": { "x-api-key": "your-key-here" }
}
}
}
```
Add to `~/.gemini/settings.json`. The key is `httpUrl`:
```json theme={null}
{
"mcpServers": {
"octen": {
"httpUrl": "https://mcp.octen.ai/mcp",
"headers": { "x-api-key": "your-key-here" }
}
}
}
```
```bash theme={null}
codex mcp add octen --url https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"
```
Clients that speak only stdio (Zed, Warp, Raycast, Cline) reach the endpoint through the `mcp-remote` bridge. There is no space after the colon in `--header`:
```json theme={null}
{
"mcpServers": {
"octen": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.octen.ai/mcp",
"--header", "x-api-key:your-key-here"
]
}
}
}
```
### Run It Locally
Run the server with `npx`. Set your key in `OCTEN_API_KEY`.
```bash theme={null}
claude mcp add --scope user octen \
-e OCTEN_API_KEY=your-key-here \
-- npx -y octen-mcp
```
Add to `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"octen": {
"command": "npx",
"args": ["-y", "octen-mcp"],
"env": {
"OCTEN_API_KEY": "your-key-here"
}
}
}
}
```
Add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"octen": {
"command": "npx",
"args": ["-y", "octen-mcp"],
"env": {
"OCTEN_API_KEY": "your-key-here"
}
}
}
}
```
Install at the user level:
[](https://vscode.dev/redirect/mcp/install?name=octen\&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Octen%20API%20Key%22%2C%22password%22%3Atrue%7D%5D\&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22octen-mcp%22%5D%2C%22env%22%3A%7B%22OCTEN_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D)
Or add to `.vscode/mcp.json`:
```json theme={null}
{
"servers": {
"octen": {
"command": "npx",
"args": ["-y", "octen-mcp"],
"env": {
"OCTEN_API_KEY": "your-key-here"
}
}
}
}
```
```bash theme={null}
codex mcp add octen \
--env 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 |
| - | - | - |
| `broad_search` | Comparisons, surveys, multi-angle search | Ranked results grouped per generated sub-query |
| `search` | Search bars, answer engines, news and source lookup | Ranked pages with relevant `highlight` and optional `full_content` |
| `image_search` | Image lookup, visual references | Ranked images with source page, dimensions, and thumbnail |
| `video_search` (beta) | Video lookup, clip discovery, media previews | Ranked videos with duration and cover |
| `extract` | Reading pages, cleaning articles | Clean content with optional highlights, `category`, and `page_structure` |
### Broad Search
Use `broad_search` for comparisons, surveys, and multi-angle research. It decomposes a query into related sub-queries from multiple angles, searches them concurrently. It supports:
* `max_queries`: 1-30 sub-queries (default 5) — raise for broader coverage
* all `search` options applied to every sub-query
```json theme={null}
{
"query": "compare cloud GPU pricing across major providers",
"max_queries": 5,
"count": 10
}
```
### Web Search
Use `search` for live web retrieval. It supports:
* `count`: 1-100 results
* `include_domains` / `exclude_domains`
* `include_text` / `exclude_text`
* `time_basis`, `time_range`, `start_time`, and `end_time`
* `language`: restrict result languages
* `highlight` snippets or `full_content`
* `include_images`
* `format` (`text` or `markdown`) and `safesearch`
```json theme={null}
{
"query": "latest AI agent benchmark results",
"count": 5,
"time_range": "week"
}
```
### Image Search
Use `image_search` for image lookup and visual references. It supports:
* `query` (text) or a reference image (`image_url`, or base64 bytes in `image_data`): use one or the other, not both
* `count`: 1-10 results
* `include_domains` / `exclude_domains`
* `safesearch`
```json theme={null}
{
"query": "red sports car",
"count": 5
}
```
### Video Search
*In beta — contact us for beta access.* Use `video_search` for video lookup, clip discovery, and media previews. It supports:
* `query`
* `count`: 1-10 results
* `time_range`, `start_time`, and `end_time`
* `safesearch`
```json theme={null}
{
"query": "how to make espresso",
"count": 5
}
```
### 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`, and `include_audio`
```json theme={null}
{
"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:
```json theme={null}
{
"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_extra_count": 0 },
"latency": 237
}
}
```
Extract returns one result per URL:
```json theme={null}
{
"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.
## Configuration
| Variable | Required | Default |
| - | - | - |
| `OCTEN_API_KEY` | Yes | - |
| `OCTEN_API_URL` | No | `https://api.octen.ai` |
***
Last modified on October 13, 2026
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.