octen-mcp

octen-mcp

Octen 的 MCP 服务。将其接入 Claude、Cursor、VS Code、Windsurf 或任何 MCP 客户端，即可为你的 Agent 提供实时网页搜索和 URL 提取能力。

核心功能：

• search / news_search：搜索实时网页，支持按域名、文本、语言和时间筛选。
• broad_search：将查询拆分为多个子查询，并行搜索，并按子查询分组返回结果，以覆盖更广泛的内容。
• extract：将一个或多个 URL 转换为整洁、适合大模型处理的内容。
• image_search（Beta 阶段 — 请联系我们获取 Beta 访问权限）：通过文本查询、参考图片 URL 或 Base64 图片数据搜索网页图片，三者必须且只能使用一种。
• video_search（Beta 阶段 — 请联系我们获取 Beta 访问权限）：通过文本查询搜索网页视频。

Octen 对 Agent 的实用之处在于，extract 返回的不仅仅是网页文本。每个成功的结果还包括：

• category：网页内容主题
• page_structure：网页类型
• highlights：传入 query 时返回的排序片段

这样，Agent 就能在为完整正文消耗 token 之前，跳过登录墙、导航页和不相关的 URL。

为什么选择 Octen MCP

快速

网页搜索平均耗时 62ms。速度足以支持多步骤 MCP 工作流。

准确

由 SOTA 文本和 VL 嵌入模型提供支持。来源质量更高，幻觉更少。

内容新鲜

实时网页数据，按分钟更新。适用于新闻、价格和快速变化的网页。

高效

整洁的重点片段、可选的 full_content 和网页标签，让模型上下文保持相关。

快速开始

你需要从 octen.ai 获取 OCTEN_API_KEY——如果客户端通过 OAuth 登录，则无需密钥（参见改用登录）。

两种连接方式。 两种方式都提供相同的六种工具。

	端点	适用场景
托管（推荐）	https://mcp.octen.ai/mcp	无需安装或更新。适用于任何支持远程 MCP 的客户端。
本地	npx -y octen-mcp	不支持远程连接的客户端、隔离网络环境，或希望在自己的设备上运行进程时。

Node 兼容性（仅限本地）： 0.4.2 及更高版本可在所有受支持的 Node 版本（>= 18.17）上运行，包括 Node 26+。0.4.1 及更早版本在内置 undici 为 v8+ 的主机上（Node 26 及更高版本）调用时都会失败，并显示 Network error … code=UND_ERR_INVALID_ARG cause=invalid onError method — 如果 你看到此错误，请升级软件包（或使用 Node <= 24）。

连接到托管端点

传递密钥

有三种方式，按以下顺序尝试。优先使用请求头——URL 中的密钥会暴露在代理日志、浏览器历史记录和 Referer 请求头中。

格式	适用场景
x-api-key: <key>	默认方式。
Authorization: Bearer <key>	客户端只提供一个请求头字段时。
将 ?octenApiKey=<key> 附加到 URL	客户端只接受 URL 时。

也可以使用 OAuth，无需粘贴任何密钥——参见改用登录。

按客户端

Claude Code — 安装插件。插件包含托管服务和两个技能：octen-web-search（将请求路由到合适的工具）和 octen-research（多源研究工作流）：

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

也可以在会话中执行：/plugin marketplace add Octen-Team/octen-mcp，然后执行 /plugin install octen@octen。

插件不包含凭据。首次调用会收到 401，随后 Claude Code 会引导你完成 OAuth 登录 — 如果想自行启动，请运行 /mcp。若要单独注册服务并使用密钥：

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

Cursor — 将此仓库克隆到 Cursor 的本地插件目录，即可一步获取托管服务和两个技能：

git clone https://github.com/Octen-Team/octen-mcp ~/.cursor/plugins/local/octen

Cursor Marketplace 列表正在等待审核；发布后，本节会指向该列表。若只需接入服务，请将其添加到 ~/.cursor/mcp.json：

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

VS Code — 使用 .vscode/mcp.json（工作区）或用户配置。请注意，键名是 servers，不是 mcpServers，并且必须显式指定 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 — macOS 和 Linux 上使用 ~/.config/devin/mcp_config.json（如果设置了 $XDG_CONFIG_HOME，则使用 $XDG_CONFIG_HOME/devin/），Windows 上使用 %APPDATA%\devin\mcp_config.json。Cascade 接受远程服务的 serverUrl 或 url； 旧版 Agent 的路径为 ~/.codeium/windsurf/mcp_config.json：

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

Gemini CLI — 使用 ~/.gemini/settings.json。键名是 httpUrl：

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

Claude Desktop 直接使用 URL — 无需配置文件或桥接。在 Settings → Connectors 中，点击 Add custom connector，将其命名为 Octen，然后输入：

https://mcp.octen.ai/mcp

高级设置留空：OAuth Client ID 和 Secret 字段用于无法自行注册客户端的服务，而我们的服务可以。Claude 会提示你登录；你批准后，系统会为该连接签发 Octen 密钥。

连接器对话框没有请求标头字段，因此 API 密钥需放在 URL 中：

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

两种方式中，登录更好 — URL 并非承载机密信息的安全媒介，而且无需修改你这边的任何设置，就可以从账户中撤销登录授权。另请注意，Claude 是从 Anthropic 的服务器而非你的设备连接，因此自托管部署必须能从公共互联网访问，这种方式才能正常工作；私有部署则需要使用下方的桥接。

Zed、Warp、Raycast 和 Cline 都可以直接连接远程服务 — 将它们指向端点并登录即可。Raycast 的 HTTP 传输支持 OAuth 类型 Dynamic，应选择此项：此服务支持动态客户端注册，因此无需预先设置客户端 ID。

{
  "mcpServers": {
    "octen": {
      "url": "https://mcp.octen.ai/mcp"
    }
  }
}

没有标头字段的客户端可将密钥放在 URL 中： https://mcp.octen.ai/mcp?octenApiKey=your-key-here。

仅当客户端仍完全无法连接远程服务时，才使用在本地运行并转发每个请求的 mcp-remote 桥接。请注意，--header 中的冒号后面不能有空格 — 值会按第一个冒号拆分：

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

改为登录

如果部署配置了授权服务器 — 托管服务已配置 — 未提供凭据的请求会收到 401 + WWW-Authenticate: Bearer resource_metadata="…"。这是 MCP 客户端用来启动 OAuth 工作流的信号，因此支持 OAuth 的客户端会提示你登录，而不是索要密钥。

若要将已有密钥的连接切换到 OAuth，请将其指向 https://mcp.octen.ai/mcp/oauth（或追加 ?login）。即使已提供密钥，此路径也会发出质询，这是触发切换的唯一方式 — 附带密钥时，常规端点没有理由这样做。

加载更少的工具

?tools=search,extract 会将连接限制为你指定的工具，适用于 tools/list 和 tools/call：

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

客户端会将每个已公布工具的完整架构加载到模型的上下文中，因此只需一两个工具时，缩小工具集确实能节省资源。如果名称未知，系统会拒绝请求并返回列出有效名称的 400，而不是让连接悄无声息地缺少工具。

改为在本地运行

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

Agent	一行安装命令
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"}}'（或点击上方的徽章）
Cursor	添加到 Cursor（然后编辑密钥），或将上面的 JSON 用于 ~/.cursor/mcp.json
Claude Desktop	没有 CLI。对于托管端点，请使用 Settings → Connectors → Add custom connector（见上文）；对于本地安装，请使用配置文件（见下文）

配置文件位置

• Claude Desktop：~/Library/Application\ Support/Claude/claude_desktop_config.json — 仅本地（stdio）安装时需要；托管端点应改为作为连接器添加
• Cursor：~/.cursor/mcp.json
• VS Code 工作区：.vscode/mcp.json（使用 servers 而不是 mcpServers）
• Windsurf：~/.codeium/windsurf/mcp_config.json
• Gemini CLI：~/.gemini/settings.json
• Cline / 其他客户端：将其粘贴到该客户端的 MCP 设置中

故障排除

每次调用都返回 401。 凭证没有传到服务端，或者尚未完成登录。在支持登录的客户端中，从 MCP 设置中授权连接。如果客户端通过密钥进行身份验证，请检查请求头名称——x-api-key 或 Authorization: Bearer——如果你使用的是 mcp-remote，还要确认 --header 中冒号后没有空格。

工具未显示。 大多数客户端只会在启动时读取一次 MCP 配置；编辑配置后请重启客户端。如果配置中使用了客户端不支持的键名（url、serverUrl 或 httpUrl），客户端根本不会联系服务端——请参阅上面的各客户端说明。

406 Not Acceptable。 请求的 Accept 请求头必须同时列出 application/json 和 text/event-stream。客户端会自动设置这些内容；手动编写的 curl 探测通常不会，因此产生的 406 看起来像是身份验证失败。

400 错误提及 tools。 ?tools= 中的名称不在此部署提供的工具之列。错误会列出可用工具。

工具报错，显示 code=403 … beta access。 image_search 和 video_search 处于 Beta 阶段，并按账户启用；错误消息会说明如何申请访问权限。

错误消息会说明发生了什么。 调用失败时会报告失败的依赖项及原因——例如超时、连接代码、令牌过期时长——并附上 API 返回的 Octen 自身 request_id。提交支持请求时请附上此 ID；工程师可以据此查询。

工具

工具	功能	最适合
search	在实时网络上搜索，并提供域名、文本、语言（ISO 639-1）、时间和内容筛选选项	单次有针对性的网络搜索
news_search	使用与 search 相同的引擎，但仅搜索新闻	时事和最新报道
broad_search	将查询拆分为最多 max_queries 个子查询，并发搜索并返回分组结果（每个子查询支持与 search 相同的选项，包括 language 筛选器）	研究式、多角度的信息收集
extract	获取 1-20 个 URL，并返回清理后的内容、标签和可选的重点摘要	内容摘要、RAG、事实查找
image_search	处于 Beta 阶段——请联系我们申请 Beta 访问权限。 根据文本查询在网络上搜索图片（可选参考 image_url）	查找图片、照片和视觉参考资料
video_search	处于 Beta 阶段——请联系我们申请 Beta 访问权限。 根据文本查询在网络上搜索视频	查找视频、片段和影像

这六种工具就是全部功能范围，这是有意为之。Embeddings、chat completions、Answer 和 Research 都是 Octen API，本服务特意不提供这些功能——请通过 Python SDK 或 CLI 使用它们。Agent 能看到的工具就会被尝试使用，因此工具列表只保留真正值得列出的工具。

参考文档：

• Search：docs.octen.ai/api-reference/search
• Extract：docs.octen.ai/api-reference/extract

参数

从每个工具发布的 schema 中转录而来，并且会强制执行这些规则，因此任何不符合约定的值都会在发起调用前被拒绝，并显示指出相应字段的消息。限制与 API 参考一致；如果两者不一致，测试就会失败。

image_search 必须且只能接受 query、image_url 或 image_data 中的一个。

query 不能为空：空字符串会被 schema 拒绝，纯空白字符串则会被处理程序拒绝。两者都不会到达 API。

timeout 有两种不同含义。 对于 search、news_search、 broad_search、image_search 和 video_search，它是此服务为调用设置的 HTTP 截止时间——它会从请求正文中移除，绝不会发送给 API。对于 extract，它是 API 文档规定的每个 URL 的抓取时间预算 （1-60s），会包含在请求正文中；extract 调用的本地截止时间会在此基础上增加余量，因此调高 timeout 会同时延长两者。

include_domains 和 exclude_domains 中重叠的域名会按原样传递。目前，API 会对同时列在两者中的域名返回验证错误；已发布的 参考文档则说明排除项优先。在两者达成一致之前，此服务既不会悄悄删除筛选条件，也不会调整其顺序——你会收到 API 的响应。

search

参数	类型	必填	限制	默认值
query	字符串	是	1–500 个字符
topic	字符串		general / news	"general"
count	整数		1–100	5
include_domains	数组		≤1200 项；每项 ≤60
exclude_domains	数组		≤1200 项；每项 ≤60
include_text	数组		≤5 项；每项 ≤30
exclude_text	数组		≤5 项；每项 ≤30
time_basis	字符串		auto / published / crawled	"auto"
time_range	字符串		day / week / month / year / d / w / m / y
start_time	字符串
end_time	字符串
format	字符串		text / markdown	"text"
safesearch	字符串		off / strict	"strict"
language	数组			[]
highlight	对象		enable、max_tokens
full_content	对象		enable、max_tokens
include_images	布尔值			false
timeout	整数		1–60

news_search

参数	类型	必填	限制	默认值
query	字符串	是	1–500 个字符
count	整数		1–100	5
include_domains	数组		≤1200 项；每项 ≤60
exclude_domains	数组		≤1200 项；每项 ≤60
include_text	数组		≤5 项；每项 ≤30
exclude_text	数组		≤5 项；每项 ≤30
time_basis	字符串		auto / published / crawled	"auto"
time_range	字符串		day / week / month / year / d / w / m / y
start_time	字符串
end_time	字符串
format	字符串		text / markdown	"text"
safesearch	字符串		off / strict	"strict"
language	数组			[]
highlight	对象		enable、max_tokens
full_content	对象		enable、max_tokens
include_images	布尔值			false
timeout	整数		1–60

broad_search

参数	类型	必填	限制	默认值
query	字符串	是	1–500 个字符
max_queries	整数		1–30	5
topic	字符串		general / news	"general"
count	整数		1–100	5
include_domains	数组		≤1200 项；每项 ≤60
exclude_domains	数组		≤1200 项；每项 ≤60
include_text	数组		≤5 项；每项 ≤30
exclude_text	数组		≤5 项；每项 ≤30
time_basis	字符串		auto / published / crawled	"auto"
time_range	字符串		day / week / month / year / d / w / m / y
start_time	字符串
end_time	字符串
format	字符串		text / markdown	"text"
safesearch	字符串		off / strict	"strict"
language	数组			[]
highlight	对象		enable、max_tokens
full_content	对象		enable、max_tokens
include_images	布尔值			false
timeout	整数		1–300

extract

参数	类型	必填	限制	默认值
urls	数组	是	≤20 项；每项 ≤2048
query	字符串		≤500 个字符
max_age_seconds	整数		300–31536000	86400
format	字符串		markdown / text	"markdown"
timeout	整数		1–60	30
include_images	布尔值			false
include_videos	布尔值			false
include_audio	布尔值			false
mode	字符串		standard / advanced / auto	省略（API 使用 standard）
include_links	对象		scope（prefer_internal / prefer_external）、max_links（1–1000）	{} → prefer_internal、200

选择 mode：

场景	mode
新闻 / 博客 / 文档 / 产品页面（普通网站）	standard（或省略）
已知的难处理网站（Reddit / X / LinkedIn / ResearchGate / 反机器人机制 / SPA）	advanced
混合批次，不确定哪些网站难处理	auto
注重成本，主要是普通网站	standard
优先考虑质量，主要是难处理的网站	advanced

对于难处理的网站，standard 可能会在内容为空或仅有框架内容时报告 success； 只需对这些 URL 使用 advanced 重试。advanced 速度较慢，价格是 standard 的 2.5 倍；auto 会按每个 URL 实际使用的模式计费。使用 advanced 或 auto 时，请调高 timeout（例如设为 60）。每个结果都会显示其 resolved_mode，而元数据行中的 billed: 计数取自 meta.usage.successful_by_mode，这是计费的权威依据。

image_search

参数	类型	必填	限制	默认值
query	字符串		≤500 个字符
image_url	字符串
image_data	字符串		≤5242880 个字符
topic	字符串		general / design	"general"
count	整数		1–10	5
include_domains	数组
exclude_domains	数组
safesearch	字符串		off / strict	"strict"
html_snippet	对象		enable、max_tokens
timeout	整数		1–60

video_search

参数	类型	必填	限制	默认值
query	字符串	是	1–500 个字符
count	整数		1–10	5
time_range	字符串		day / week / month / year / d / w / m / y
start_time	字符串
end_time	字符串
safesearch	字符串		off / strict	"strict"
timeout	整数		1–60

让工具始终加载（可选）

在启用了 MCP 工具搜索 的客户端中（Claude Code 默认启用），工具会被延迟加载——模型会运行 ToolSearch 步骤，按需加载工具。如果你希望从第一轮开始就加载 Octen 工具（无需发现步骤），请在 .mcp.json 中为服务设置 alwaysLoad（Claude Code v2.1.121+）：

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

每个始终加载的工具都会在每一轮占用上下文，而 alwaysLoad 会阻塞启动，直到连接到服务（连接超时上限约为 5 秒），因此只应对经常使用的工具启用。为了控制成本，只将流量最高的工具（例如 search 和 broad_search）在各自的 _meta 中标记为 "anthropic/alwaysLoad": true，其余工具则继续延迟加载。

为什么 Agent 喜欢它

大多数信息提取工具只会做到“这是页面正文”。Octen 能更早地帮上一步：

• 尽早跳过无效页面：page_structure.primary == "No Main Content" 会告诉 Agent，它遇到了登录墙、空壳页面或类似的非内容页面。
• 尽早按主题筛选：category 可帮助工作流在嵌入或总结之前忽略目标领域之外的页面。
• 减少上下文用量：当用户需要某个具体事实而非整个页面时，query 会返回 highlights。

完整的决策树和集成模式，请参阅 docs/best-practices.md。

提示词示例

• 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.

自托管 HTTP 服务

上面的托管端点运行的就是同一份代码；你也可以自行运行：

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

端点：POST /mcp（无状态 Streamable HTTP）和 GET /healthz。它在设计上是无状态的——没有需要保留的会话，因此只需通过负载均衡器运行更多副本即可扩展。凭据随请求传递，绝不会来自服务自身的环境：不带凭据的请求会失败，而不会悄悄消耗主机的密钥。

除非进行配置，否则授权功能处于关闭状态。 设置 OCTEN_OAUTH_AUTHORIZATION_SERVER 和 OCTEN_MCP_RESOURCE 后，服务会公布 RFC 9728 受保护资源元数据，并对未经凭据验证的请求返回 401 挑战。若不设置这些变量，服务就不会公布任何内容——实例绝不能将客户端指向自己并未配置的授权服务器——缺少密钥则会在调用时显示出来。

参数验证。 每个工具声明的 inputSchema 都会被强制执行，而不仅仅是公布出来：包括类型、范围、字符串长度、数组大小、枚举、必需参数以及属性列表本身。不符合约定的调用会在发送到 API 之前被拒绝，并提示具体字段。

以 base64 形式发送图像。 image_search 接受编码后最大为 5MB 的 image_data，该数据会随 JSON-RPC 请求体发送。OCTEN_MCP_MAX_BODY 默认值为 6 MiB，因此无需配置即可正常使用；OCTEN_MCP_MAX_INFLIGHT_BODY（24 MiB）则单独限制所有进行中请求体的总占用，因为单个请求的上限无法应对大量并发请求。

环境变量

变量	必填	默认值	说明
OCTEN_API_KEY	是	—
OCTEN_API_URL	否	https://api.octen.ai
OCTEN_ENABLE_BETA_TOOLS	否	on	设置为 false/0/off/no，可在发现时隐藏 Beta image_search / video_search 工具。
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	否	—	自 0.4.0 起支持。Node 内置的 fetch 默认会忽略这些变量，因此在 0.4.0 之前，即使机器上的其他工具都能访问 API，服务也无法在代理后访问 API。请在客户端配置中显式设置这些变量——见下文；大多数 MCP 客户端不会传递 shell 环境变量。
OCTEN_KEEP_ALIVE_MS	否	60000	空闲连接保持可复用状态的时长。undici 默认的 4s 意味着几乎每次调用都要重新进行完整的 TLS 握手（实测约 515ms）。针对 api.octen.ai 测得 60s；该服务会在 60s 到 90s 之间关闭空闲连接——将时长设在此范围内，意味着我们总能先释放连接，而不会将请求分发到源站已关闭的套接字上。如果将 OCTEN_API_URL 指向其他地址，请重新测量。
OCTEN_KEEP_ALIVE_MAX_MS	否	600000	当源站公布自己的 Keep-Alive 提示时，上述时长的上限。api.octen.ai 不会发送此提示。
OCTEN_CONNECT_TIMEOUT_MS	否	10000	与 api.octen.ai 建立出站连接的最长等待时间——这与上文提到的 MCP 客户端自身启动连接超时无关。如果连接偶尔失败，可调低此值（例如 5000），让自动重试更早触发。
OCTEN_RETRY	否	on	设置为 false/0/off/no，可禁用连接级故障时的一次自动重试。如果原始请求实际上已到达服务器，重试会消耗配额。
OCTEN_HTTP2	否	off	启用 HTTP/2。实测表明，对于通常一次只发出一个请求的模式，速度没有提升；而且并非所有 CONNECT 代理都能可靠支持——如果你会并行发出大量工具调用，不妨试试。
OCTEN_MCP_DEBUG	否	off	在 stderr 上记录请求跟踪信息（stdout 承载 MCP 帧）。见下文。

仅限远程 HTTP 形式

这些变量仅由 octen-mcp-http 读取；stdio 入口会忽略它们。

变量	必填	默认值	说明
PORT	否	8080	0 表示选择一个临时端口。
OCTEN_MCP_LOG	否	人类可读文本	json 会为每个事件输出一个 JSON 对象，供日志管道使用。
OCTEN_MCP_MAX_BODY	否	6291456	每个请求的正文大小上限，单位为字节，按接收的字节数强制执行。超过上限时返回 413。此值足以让 image_search 的 image_data（编码后为 5MB）在未配置的情况下正常工作；如果此部署从不发送图像，可调低此值。
OCTEN_MCP_MAX_INFLIGHT_BODY	否	25165824	所有正在处理的请求正文同时占用的总字节数上限。单个请求的大小上限可阻止一个超大请求；此项可阻止大量普通请求。超过上限时返回 503 + Retry-After。实测常驻内存开销约为此值的十倍，因为 base64 正文会以 UTF-16 字符串形式存在两到三份。
OCTEN_MCP_BODY_DRAIN_MS	否	2000	返回 413 后，继续丢弃剩余正文的最长时间，以确保 413 响应本身能够送达。
OCTEN_DRAIN_TIMEOUT_MS	否	310000	收到 SIGTERM 后，允许正在处理的调用完成的最长时间。必须小于 Pod 的 terminationGracePeriodSeconds，并且大于最长工具预算（broad_search 为 300s）。
OCTEN_APPS_CHALLENGE_TOKEN	否	—	插件目录域名验证令牌。设置后，GET /.well-known/openai-apps-challenge 会将此值原样作为纯文本提供（正文必须仅包含令牌）；未设置时，该路径返回 404。此设计有意允许匿名访问，类似 PRM：令牌由目录生成，供其自己的验证器读取，并非此部署的秘密。

OAuth。 除非设置了前两个变量，否则 OAuth 会关闭，这样实例就不会声明自己拥有并不存在的授权服务器。

变量	必填	默认值	说明
OCTEN_OAUTH_AUTHORIZATION_SERVER	OAuth 必填	—	授权服务器基础 URL。会与令牌的 iss 逐字节比较，并用于构建 JWKS URL——末尾不能有斜杠；进程发现末尾有斜杠时会拒绝启动，因为这会导致所有令牌都被拒绝。
OCTEN_MCP_RESOURCE	OAuth 必填	—	此部署的公共 URL，例如 https://mcp.example.com/mcp。会与令牌的 aud（RFC 8707）逐字节比较，因此多余的末尾斜杠会导致所有调用失败。代理后无法推断此值，因此必须显式设置。
OCTEN_OAUTH_RESOLVE_URL	OAuth 必填	—	用于将授权凭证兑换为 API 密钥的内部端点。必须可通过私有网络访问；公共地址无法提供此服务。
OCTEN_OAUTH_RESOLVE_TOKEN	OAuth 必填	—	发送到该端点的共享密钥，位于 X-Octen-Service-Token 中。
OCTEN_OAUTH_RESOLVE_CACHE_TTL_MS	否	60000	已解析授权凭证的复用时长。这就是撤销传播窗口：现在撤销的令牌在此时长内仍可使用。设为 0 时，每次调用都会重新解析，但代价是每个工具调用都必须经过该服务。
OCTEN_JWKS_REFETCH_COOLDOWN_MS	否	10000	因未知密钥 ID 而触发的 JWKS 重新获取之间的最短间隔。触发条件来自未经验证的令牌标头，因此如果没有此间隔，每个此类请求都会变成发送到授权服务器的一个请求。调低此值会按相同比例扩大请求量。

在 Claude Desktop 中设置这些变量（以及日志的位置）

MCP 服务不会继承你的 shell 环境变量。Claude Desktop 启动它们时会提供 HOME、LOGNAME、PATH、SHELL 和 USER——除此之外，只有你在服务的 env 块中设置的变量。系统范围内配置的代理不会被读取；必须与 API 密钥一同显式指定：

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": {
        "OCTEN_API_KEY": "your-key-here",
        "HTTPS_PROXY": "http://proxy.example:8080"
      }
    }
  }
}

编辑配置后，重启 Claude Desktop——它会在启动时读取配置。

服务输出会写入：

• macOS：~/Library/Logs/Claude/mcp-server-octen.log
• Windows：%APPDATA%\Claude\logs\mcp-server-octen.log

服务写入 stderr 的所有内容，包括下文的追踪信息，都会写入此处。

诊断调用缓慢或失败

排查期间，请在上方的 env 块中添加 "OCTEN_MCP_DEBUG": "1"， 排查完后将其移除——客户端会将日志写入一个永不轮转的文件，因此如果一直启用，安装期间该文件会不断增大。

启用后，每次调用都会跟踪并输出到 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

每个字段都对应一个具体问题：

• call #N received 时间戳——调用到达此进程的时间。将它与 MCP 客户端发起工具调用的时间相减：差值就是完全发生在 octen-mcp 之外的耗时，可能在宿主端或两者之间的中继中。仅用客户端的秒表无法区分这部分时间与我们负责的耗时。
• connect … established in Xms——表示发生了握手，以及握手耗时。connect FAILED 则会指出失败阶段和错误代码。
• peer= / tls= / alpn=——连接实际到达的地址（API 主机名采用任播，因此仅凭主机名无法判断连接到了哪个边缘节点），以及协商出的 TLS 版本和协议——若不匹配，通常会表现为无法解释的握手缓慢或失败。
• socket=new / socket=reused——表示此次调用是否需要进行握手。这有助于区分“服务很慢”和“连接在调用间被丢弃”。
• elapsed 与 handler_total——分别表示 HTTP 请求耗时和工具处理器耗时。两者差距较大，说明耗时在请求组装或响应格式化，而非网络。
• request_id——仅在 此跟踪记录中 使用：由客户端生成的关联 ID，在重试期间保持不变，用于关联一次调用的各次尝试。它不会出现在面向用户的错误消息中，这是有意为之：Octen 支持团队无法通过它查询记录（网关不会记录该标头），而标为 request_id 的 ID 看起来却像是可以查询。错误消息只包含已确认可在 Octen 端搜索到的 ID——目前恰好只有一个：API 错误封装中的服务器自身 request_id。

失败信息会指出具体原因，而不只是 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 表示连接从未建立，ECONNRESET 表示连接已建立后又被断开，而 ENOTFOUND 表示 DNS 问题——这是三种不同的问题，责任方也各不相同。

请求超时：search 和媒体工具默认超时为 30s，broad_search 为 120s（可提高至 300s），而 extract 的超时为每个 URL 的预算加上额外缓冲时间。搜索工具接受 timeout 参数来覆盖默认值；extract 的 timeout 是服务器端针对每个 URL 的抓取预算，因此客户端的超时时限根据它计算，而非与它相等。自动重试与首次尝试共用同一截止时间，因此所述超时限制适用于整个调用，包括重试。

本地开发

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

更多文档

• Agent 集成最佳实践：docs/best-practices.md
• Search API 参考：docs.octen.ai/api-reference/search
• Extract API 参考：docs.octen.ai/api-reference/extract

许可证

MIT © Octen