MCP 客户端

任何兼容 MCP 的客户端都可以直接连接 OpenViking 内置的 /mcp 端点——无需安装插件或启动额外进程。适用于 Cursor、Trae、Manus、Claude Desktop、ChatGPT 等。

快速配置

大多数 MCP 客户端使用标准 mcpServers 格式：

json

{
  "mcpServers": {
    "openviking": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

本地服务未配置 root_api_key 时（dev 模式）无需认证。

各平台注意事项

Claude Code

Claude Code 需要额外指定 "type": "http"，通过命令行添加：

bash

claude mcp add --transport http openviking \
  https://your-server.com/mcp \
  --header "Authorization: Bearer your-api-key-here"

加 --scope user 使配置全局生效。

如果你需要免工具调用的自动召回与自动捕获，请使用 Claude Code 记忆插件。

Trae / Cursor / ChatGPT / Codex / OpenCode

使用上面的标准 mcpServers 配置即可——均已通过 API Key 鉴权验证。

Claude Desktop / Claude.ai (OAuth)

这些客户端要求 OAuth 2.1——无法直接传 API Key。OpenViking 自带原生 OAuth 2.1 实现，无需外部代理。

如果你已经为 OpenViking 服务配好了 HTTPS，直接连接 https://your-server.com/mcp 端点即可——客户端会自动引导你完成 OAuth 授权流程。

HTTPS 配置、部署模板和完整授权流程详见 OAuth 2.1 指南和公网访问指南。

可用工具

连接后 OpenViking 暴露 14 个工具：

工具	说明
`search`	跨记忆、资源、技能的语义搜索
`read`	读取一个或多个 `viking://` URI
`list`	列出 `viking://` 目录下的条目
`store`	存储消息到长期记忆
`add_resource`	添加本地文件或 URL 作为资源
`grep`	正则内容搜索
`glob`	按 glob 模式查找文件
`forget`	删除 `viking://` URI
`code_outline`	展示文件的符号结构
`code_search`	跨目录搜索符号名
`code_expand`	返回单个符号的完整源码
`health`	检查 OpenViking 服务状态
`list_watches`	列出自动刷新订阅
`cancel_watch`	取消 watch 任务

工具参数、渐进式文件上传和高级配置见 MCP 集成指南。

故障排查

现象	修复
连接被拒绝	确认 `openviking-server` 正在运行：`curl http://localhost:1933/health`
认证错误	确保客户端配置中的 API Key 与服务端一致。见鉴权指南

参见

MCP 集成指南 — 工具参数、渐进式上传、OPENVIKING_PUBLIC_BASE_URL
OAuth 2.1 指南 — 用于 Claude Desktop、Claude.ai、Cursor
MCP 规范

MCP 客户端 ​

快速配置 ​

各平台注意事项 ​

Claude Code ​

Trae / Cursor / ChatGPT / Codex / OpenCode ​

Claude Desktop / Claude.ai (OAuth) ​

可用工具 ​

故障排查 ​

参见 ​