Claude Code 如何连接本地或远程 MCP 知识库服务器？

Claude Code 连接知识库 MCP 服务器时，先判断服务器是本地进程还是远程网络服务。本地服务器使用 stdio，由 Claude Code 启动命令并通过标准输入输出通信；远程服务器优先使用 Streamable HTTP，配置完整的 HTTPS 端点，并按服务要求完成 OAuth 或请求头认证。两种方式都能提供搜索、读取和写入知识库的工具，但启动位置、凭据管理与共享范围完全不同。

配置完成并不等于连接成功。应使用 `claude mcp list`、`claude mcp get` 和会话内 `/mcp` 面板检查状态、工具数量、认证要求与错误详情，再用一条只读查询验证返回内容来自预期知识库。项目级配置还需要用户信任工作区并批准服务器，不能让克隆下来的仓库自行启用外部工具。

先区分本地与远程服务器

本地 stdio 服务器适合知识库文件与 Claude Code 位于同一台电脑的场景。配置中包含 command、args 和必要环境变量，Claude Code 在会话需要时启动子进程。它不公网端口，网络暴露面较小，也可以直接使用当前项目目录或明确允许的文件根目录。

远程 MCP 服务器已经由其他进程或服务托管，Claude Code 只保存 URL 和认证信息。官方建议远程服务优先采用 HTTP，因为它最适合云端服务并支持 OAuth。旧服务器可能只提供 SSE，Claude Code 可在新版中先尝试 HTTP，再自动回退；只有明确需要服务端主动推送事件时才考虑 WebSocket。

判断配置类型不能只看示例文件名。如果文档给出 npx、uvx、Python 或二进制启动命令，它通常是本地 stdio；如果给出 HTTPS URL，它属于远程 HTTP；如果给出 mcpServers JSON，则需要查看内部是 command 还是 url。把 URL 条目误写成 stdio 会出现缺少 command 等配置错误。

本地知识库服务器的添加命令

stdio 服务器通过 `claude mcp add` 添加，服务器名称位于 Claude 参数之后，实际启动命令必须放在双横线后。双横线用于分隔 Claude Code 自身选项与服务器命令参数，缺失时，端口、目录或包管理器参数可能被 Claude CLI 错误解析。

claude mcp add --transport stdio knowledge 
  -- npx -y PACKAGE_NAME

Python 或 uvx 服务器采用相同结构，只替换双横线后的启动命令。需要 API Key、知识库路径或其他环境变量时，可使用 `--env KEY=value`。敏感值不要写进项目级 `.mcp.json`，因为该文件通常会提交到仓库。团队共享配置可在文件中引用环境变量，让每个成员在本机提供真实凭据。

claude mcp add --transport stdio knowledge 
  --env KNOWLEDGE_DIR=/absolute/path/to/notes 
  -- uvx PACKAGE_NAME

本地服务器若需要识别项目根目录，可以读取 Claude Code 注入到服务器进程中的 CLAUDE_PROJECT_DIR。该变量指向会话启动时的稳定项目根，不会因后续添加工作目录而变化。若服务器需要限制文件访问，更完整的方式是实现 MCP roots/list，让 Claude Code 返回当前启动目录以及用户明确授权的附加目录。

远程 HTTP 服务器的添加命令

远程知识库优先使用 HTTP 传输，并填写服务文档给出的完整端点路径。URL 可能以 `/mcp` 结尾，也可能挂在根路径，不能凭经验自行添加或删除。Bearer Token 可通过 header 参数传入；支持 OAuth 的服务器则先添加连接，再从 `/mcp` 面板启动登录。

claude mcp add --transport http knowledge REMOTE_MCP_ENDPOINT

claude mcp add --transport http secure-knowledge REMOTE_MCP_ENDPOINT 
  --header "Authorization: Bearer TOKEN_VALUE"

JSON 配置中，远程条目必须显式包含 `type: "http"`。`streamable-http` 也可作为同义值。只有 url 没有 type 时，Claude Code 会把条目按 stdio 形状解释并跳过，常见提示是 URL 已存在但缺少类型。修复方式是补上正确 type，而不是添加虚假的 command。

{
  "mcpServers": {
    "knowledge": {
      "type": "http",
      "url": "REMOTE_MCP_ENDPOINT"
    }
  }
}

SSE 与 WebSocket 什么时候使用

SSE 传输已经被弃用，新部署应优先选择 Streamable HTTP。服务只提供旧式 SSE 时，可以仍按 HTTP 添加，让支持自动回退的 Claude Code 版本先尝试 HTTP；较旧版本或自动回退失败时，再显式使用 `--transport sse`。不要因为名称中有“流式”就把所有 HTTP 服务改成 SSE。

WebSocket 适合服务器主动向 Claude 推送事件的场景，例如知识库更新通知或外部消息通道。它需要在 JSON 配置中使用 `type: "ws"`，不能通过 `claude mcp add --transport` 直接添加。WebSocket 不支持 OAuth，只能使用静态请求头或动态头助手，因此一般的查询型知识库没有必要选择它。

选择 local、project 还是 user 作用域

作用域决定服务器配置在哪里生效。local 是默认值，只在当前项目和当前用户中可用，配置保存在用户侧，不会提交到仓库，适合带私人路径和凭据的知识库。project 把配置写入项目根目录的 `.mcp.json`，适合团队共享无敏感信息的服务器定义。user 则让服务器在当前用户的所有项目中可用，适合个人通用知识库。

claude mcp add --scope local --transport http knowledge REMOTE_MCP_ENDPOINT
claude mcp add --scope project --transport http team-kb REMOTE_MCP_ENDPOINT
claude mcp add --scope user --transport stdio personal-memory -- COMMAND

同名服务器在多个作用域出现时会按优先级覆盖，并触发冲突警告。不同项目若加载同名但不同 URL 的远程服务器，OAuth 登录也按端点分别保存。应为不同知识库使用明确名称，或删除不再需要的旧作用域配置，避免以为连接到团队库，实际却命中了个人 local 定义。

项目级 `.mcp.json` 来自代码仓库，属于可执行配置。Claude Code 要求先信任工作区并批准服务器。仓库中提交的设置不能自行批准它携带的 MCP 定义，这能阻止恶意仓库在用户打开目录时静默启动命令。首次进入陌生项目时，应检查 command、args、env 和 URL 再批准。

从其他客户端的配置迁移

服务器文档可能只给 Claude Desktop 或 Cursor 的 mcpServers JSON。Claude Code 可以使用 `claude mcp add-json`，但参数应传入 mcpServers 内部的单个服务器对象，而不是整个外层包装。服务器名称只能包含字母、数字、连字符和下划线。

claude mcp add-json knowledge 
  '{"command":"npx","args":["-y","PACKAGE_NAME"]}'

复制前先修复两类问题：url 条目必须补 type；本地条目的 command 与 args 必须保持分离。若配置使用环境变量占位符，确认变量在 Claude Code 启动环境中存在，并为可选值提供默认。缺失变量不会总是让配置完全停止加载，可能以未展开文本继续运行并产生难以理解的连接错误。

远程服务器如何完成 OAuth

支持 OAuth 的远程知识库在首次连接时会显示 Needs authentication。进入 `/mcp` 面板选择对应服务器并执行认证，Claude Code 会打开浏览器完成授权。成功后令牌由客户端保存，后续调用自动携带凭据。删除远程服务器时，Claude Code 也会删除其保存的 OAuth 令牌与客户端注册。

命令行环境可以使用 `/mcp` 或相关认证操作完成登录。企业服务若预先分配 OAuth Client ID 与 Secret，可在配置中提供；服务使用非标准发现地址时，也可覆盖授权服务器或受保护资源元数据。只有官方文档明确要求时才使用这些高级项，错误覆盖会破坏正常自动发现。

OAuth scope 应只申请知识库操作需要的范围。只读搜索场景不应授予删除或管理权限。若服务器支持动态 scope 或细粒度工具授权，先以只读范围验证，再逐步增加写入。认证成功只说明身份有效，不代表每项工具都应自动获准执行。

静态请求头与动态凭据

Bearer Token 和 API Key 可以直接放入 headers，但静态值会保存在配置文件中。个人 local 或 user 配置应限制文件权限；project 配置不得提交真实密钥。更稳妥的方式是引用环境变量，或者使用 headersHelper 在每次连接时动态生成请求头。

动态头助手适合短期令牌、企业凭据代理或外部密钥存储。它在 Claude Code 所在机器运行，并输出当前请求头。项目级助手只有在用户信任文件夹后才会执行，因此不能利用未受信任仓库静默读取环境。助手脚本本身拥有读取可见环境变量和调用凭据系统的能力，必须像本地 MCP 命令一样审查。

排查认证时不要把完整令牌打印到终端或日志。Claude Code 的状态详情会隐藏类似凭据的文本，也不会展示带查询参数的完整 URL。若服务器把密钥嵌在 URL 中，仍应尽快改用请求头，因为 URL 更容易进入代理日志、历史记录和错误报告。

如何检查连接状态

`claude mcp add` 输出 Added 只代表配置已经写入，不代表网络握手成功。随后运行 `claude mcp list` 查看所有服务器，使用 `claude mcp get NAME` 查看具体定义与问题。进入交互会话后，`/mcp` 面板还能显示认证、批准、工具数、缓存状态以及重新连接选项。

claude mcp list
claude mcp get knowledge

# 在 Claude Code 会话内
/mcp

常见状态包括 Connected、Needs authentication、Failed to connect、Pending approval、Rejected 和 Disabled。Pending approval 通常属于项目级服务器，需在可信工作区的交互会话中批准；Disabled 表示当前项目主动停用；Rejected 则需要检查设置中的拒绝列表。

远程服务器可能显示 cached，表示工具列表来自先前发现缓存，并会在第一次实际调用时建立连接。这不是离线错误。需要立即确认连接时，可在 `/mcp` 中选择 Reconnect；认证或工具定义发生变化时，可清理认证与缓存后重新发现。

验证知识库而不冒险写入

连接后先确认工具列表中存在预期的 list、search 或 read 工具。让 Claude 列出知识库顶层项目，再搜索一个明确存在的无敏感测试词，并读取一条样例记录。对返回结果核对项目名、路径和内容，避免连接到同名旧服务器或错误环境。

写入测试应在专门的草稿目录进行。先要求工具生成 diff 或 dry-run，再创建临时笔记，读取确认后删除或归档。不要用生产资料作为首次写入目标。即使服务器实现原子写入，也不能避免模型选错文件或覆盖逻辑上较新的内容。

项目知识库还应验证 roots 边界。授权一个测试目录后，确认内部文件可读，未授权的相邻目录被拒绝。仅看到工具调用成功不能证明文件隔离有效。远程服务器的目录边界由服务端实现，Claude Code 的本地工作区权限不会自动限制远端主机文件。

工具审批与提示注入

知识库可能包含从网页、邮件或外部文档复制的恶意指令。MCP 服务器读取这些内容后，模型可能被诱导调用其他工具、泄露数据或执行写入。官方文档也强调应只连接可信服务器，并关注获取外部内容的提示注入风险。

对写入、删除、移动和批量操作保留人工审批。读取工具也应遵守最小范围，因为私人知识库的泄露不需要写权限。团队管理员可以通过允许或阻止列表限制可连接的 MCP 服务器，避免成员任意安装未经审查的知识库插件。

服务器名称与工具说明不能作为信任依据。添加前检查代码来源、版本、权限、认证方式和数据去向。本地 stdio 进程拥有运行账号权限，远程服务器则可能把内容传给第三方，两者风险不同但都需要审查。

常见配置错误

远程 JSON 有 url 却缺少 type 时，补上 http、sse 或 ws。stdio 启动参数被 Claude CLI 吞掉时，检查服务器命令前是否有双横线。添加后显示 Failed to connect 时，使用 `mcp get` 查看 HTTP 状态或错误代码，并在服务器侧核对日志。

配置值前后带不可见空格时，Claude Code 会发出警告但不会自动修剪。复制 Bearer Token 最容易带入尾部换行，导致服务器返回未授权。应编辑配置删除空白，不要反复生成新令牌掩盖问题。

OAuth 成功后仍失败时，检查回调地址、scope、系统时间和服务端发现元数据。代理后的服务应公布外部 HTTPS 来源，而不是内部 localhost。状态详情只显示来源主机而不展示路径和查询，必要时结合服务端请求日志定位完整端点。

工具未出现时，查看服务器是否声明 tools capability 却返回零个工具。启用工具搜索时，Claude 会在 ToolSearch 中等待后台连接；关闭工具搜索时则使用专门的等待机制。若远端首次发现失败，确认 DNS、证书、代理超时和身份验证，而不是只重启 Claude Code。

管理、禁用与删除服务器

不需要某个服务器时，可以临时在 `/mcp` 面板禁用，保留配置但阻止当前项目使用。永久移除则运行 `claude mcp remove NAME`，并指定它所在的 scope。远程服务器移除后，本地保存的 OAuth 注册和令牌也会清理。

claude mcp remove knowledge --scope local
claude mcp remove team-kb --scope project

删除配置不会自动停止独立运行的远程知识库服务，也不会撤销服务端 API Key。应同时在服务端删除客户端授权、轮换静态令牌，并停止不再需要的隧道。stdio 进程通常随 Claude 会话结束，但它创建的缓存、索引和配置文件仍需按服务器文档清理。

上线前检查清单

首先确认传输类型与服务器一致：本地命令使用 stdio，远程端点优先 HTTP，旧式服务才使用 SSE，事件推送才使用 WebSocket。其次确认作用域符合共享意图，个人路径和密钥不进入 project 配置，项目服务器已经人工批准。

然后确认认证有效、令牌没有隐藏空格、OAuth scope 最小化，未授权请求被拒绝。工具列表与目标知识库相符，只读测试返回正确数据，写入仅在草稿目录验证。最后检查提示注入防护、工具审批、服务端文件边界、审计和凭据撤销流程。

结论

Claude Code 连接本地或远程 MCP 知识库的关键，是把启动命令与网络端点分开处理。本地服务通过 stdio 和双横线后的命令启动，远程服务通过 HTTP URL、OAuth 或请求头连接；作用域决定配置是仅当前项目、团队共享还是用户全局可用。

完成配置后，要以 Connected 状态、正确工具列表和只读查询作为成功证据，而不是只看 Added 提示。项目级服务器需要信任与批准，敏感操作需要人工确认，凭据不能进入仓库。按“识别传输、选择作用域、配置认证、检查状态、只读验证、再开放写入”的顺序操作，可以稳定连接知识库，同时避免误连、泄密和非预期修改。