首页/ 文档/ MCP 接入（AI 助手直连）

MCP 接入（AI 助手直连）

MCP（Model Context Protocol）让 Claude、Cursor 等 AI 助手通过标准协议直连 BestNav 的开关层，与控制室同源能力。免费功能，仅管理员可生成令牌；所有调用在你自己的服务器上完成，数据不出内网。

7 个小节 · 约 3 分钟读完

功能简介

BestNav 内置一个 MCP 服务端（端点 POST /api/mcp）。接入后，你可以用自然语言让 AI 助手查询面板状态、开关 Docker 容器、触发备份/扫描等——这些动作与你在「控制室」里手动点击完全同源，受同一套权限约束。

AI 助手BestNav开关层Claude / CursorPOST /api/mcp控制室同源能力MCP / JSON-RPC鉴权后执行
图：AI 助手通过 MCP 协议连接 BestNav，再由服务端按权限调用开关层。

前置条件

  • 一个已部署并可从 AI 助手所在网络访问的 BestNav 实例（建议配好 HTTPS 与域名）
  • 以管理员（admin）账号登录——免费会员与成员账号均不能生成令牌
  • 本机已安装支持远程 MCP 的客户端（如 Claude Desktop、Cursor）

获取端点与令牌

登录 BestNav 后，打开「设置 → 常规 → MCP 接入」（console 管理台与桌面端也在右侧栏/设置中枢提供原生入口），点击「生成令牌」。系统会返回一个专用访问令牌（有效期 90 天）。

  • 端点地址：形如 https://你的域名/api/mcp
  • 访问令牌：仅生成时明文展示一次，可随时重新生成（旧令牌立即作废）
  • 一键复制：面板提供「复制客户端配置」按钮，直接得到可粘贴的 JSON

安全提示：令牌等同访问凭证，请勿泄露或提交进代码仓库；修改登录密码会使令牌同步失效。

Claude Desktop 接入

打开 Claude Desktop 配置文件（设置 → Developer → Edit Config），在 mcpServers 中加入 BestNav 条目，把 url 换成你的端点、Authorization 换成你的令牌：

Bash{ "mcpServers": { "bestnav": { "url": "https://你的域名/api/mcp", "headers": { "Authorization": "Bearer 你的令牌" } } } }

保存后重启 Claude Desktop，即可在对话中让 Claude 调用 BestNav 工具（列容器、启停服务、触发备份等）。

Cursor 接入

在 Cursor 设置 → MCP 中新增一个远程 Server，填入端点 URL 与 Bearer 令牌即可。接入后 Cursor 会拉取实时工具列表（按你的权限过滤）。

  • Type：选择 Remote（SSE/HTTP）
  • URL：https://你的域名/api/mcp
  • Headers：Authorization: Bearer 你的令牌

安全与权限

  • 专用令牌：MCP 用独立的 JWT（Type=mcp），与登录会话隔离，轮换即吊销
  • 服务端恒定打点：tools/call 由服务端标记来源，不接受客户端自报
  • 权限过滤：tools/list 基于当前账号实时可用性与权限下发，所见即可按
  • SSRF 分层防护：涉及内网探测的动作沿用面板既有的安全降级策略

常见问题

  • 提示 401 / 未授权？令牌可能已失效或被重新生成，回设置页重新复制一份
  • 看不到某些工具？工具列表按权限过滤，成员账号只会看到被授权的部分
  • 能做什么？与控制室同源：查询状态、启停 Docker、触发同步/备份/扫描等开关动作
  • 会改数据吗？只执行你明确授权的控制动作，不会自行删除文件或改库

Overview

BestNav ships a built-in MCP server (endpoint POST /api/mcp). Once connected, you can ask an AI assistant in natural language to query panel status, toggle Docker containers, trigger backups/scans and more — these actions are the same source as clicking in the Control Room and obey the same permissions.

AI AssistantBestNavControl LayerClaude / CursorPOST /api/mcpControl Room parityMCP / JSON-RPCafter auth
Diagram: an AI assistant connects to BestNav over MCP; the server invokes the control layer per your permissions.

Prerequisites

  • A BestNav instance reachable from where your AI assistant runs (HTTPS + a domain recommended)
  • Signed in as an admin — free members and member accounts cannot generate tokens
  • An MCP client that supports remote servers (e.g. Claude Desktop, Cursor)

Get Endpoint & Token

After signing in, open Settings → General → MCP Access (console and desktop also expose a native entry in the right rail / settings hub) and click “Generate Token”. You get a dedicated access token valid for 90 days.

  • Endpoint: like https://your-domain/api/mcp
  • Token: shown in plaintext only once at generation; regenerate anytime (old one revoked immediately)
  • One-click copy: the panel offers “Copy client config” to get ready-to-paste JSON

Security: the token is an access credential — never leak it or commit it to a repo; changing your login password invalidates it.

Claude Desktop

Open the Claude Desktop config (Settings → Developer → Edit Config) and add a BestNav entry under mcpServers, replacing url with your endpoint and Authorization with your token:

Bash{ "mcpServers": { "bestnav": { "url": "https://your-domain/api/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Save and restart Claude Desktop, then ask Claude to call BestNav tools (list containers, toggle services, trigger backups, and more).

Cursor

In Cursor Settings → MCP, add a new Remote server with the endpoint URL and Bearer token. Once connected, Cursor pulls the live tool list (filtered by your permissions).

  • Type: choose Remote (SSE/HTTP)
  • URL: https://your-domain/api/mcp
  • Headers: Authorization: Bearer YOUR_TOKEN

Security & Permissions

  • Dedicated token: MCP uses a separate JWT (Type=mcp), isolated from login sessions, revoked on rotation
  • Server-side stamping: tools/call source is stamped by the server, never self-reported by the client
  • Permission filtering: tools/list reflects real-time availability and your permissions
  • Layered SSRF defense: LAN-probing actions reuse the panel’s existing safe-degradation policy

FAQ

  • 401 / unauthorized? The token may have expired or been regenerated — copy a fresh one from settings
  • Missing some tools? The list is permission-filtered; member accounts only see what they’re granted
  • What can it do? Control Room parity: query status, toggle Docker, trigger sync/backup/scan actions
  • Will it change data? It only performs control actions you explicitly grant — never deletes files or edits databases on its own