1. 先搞清楚 .mcp.json 在 SAP CAP 项目里到底管什么很多刚接触 SAP CAP 的朋友第一次在项目根目录看到.mcp.json第一反应是这是不是又一个 CAP 运行时配置会不会影响cds watch、cds deploy、mbt build答案很明确——不会。.mcp.json不是给 CAP 运行时看的它是给 Claude Code 这类支持 MCPModel Context Protocol的编码助手看的项目级工具入口清单。换句话说它做的事情是告诉 Claude Code在这个 SAP CAP 项目里你可以启动一个专门服务于 CAP 开发的本地 MCP server也就是cap-js/mcp-server。启动之后Claude Code 不再只靠全文读取.cds文件去猜上下文而是可以通过一个 CAP 感知的工具层去搜索编译后的 CDS 模型、检索 CAP 官方文档再辅助你改代码、解释模型、生成实现方案。这件事为什么对 SAP CAP 特别重要因为 CAP 是模型驱动框架业务语义大量集中在 CDS model 和 annotation 里。一个 service 可能来自srv/目录的 projectionentity 可能继承自db/目录的 aspectannotation 可能落在 service 层而不是 persistence 层。Agent 如果只靠文本搜索很容易把LifecycleStatus、ApprovalStatus、OverallStatus搞混或者把普通 Express 的写法硬套到 CAP 上。有了 CAP 专用 MCP serverAgent 的认知入口就更靠近 CAP 的编译模型层。这篇内容聚焦一个具体场景SAP CAP 项目通过.mcp.json配置 MCP 服务为 Claude Code 提供 CDS 模型与项目上下文。我会把字段结构、可复制配置、验证动作、常见报错排查都讲清楚同时说明如何把 endpoint 与鉴权统一改到 TaoToken 通道让 Claude Code 走一个稳定的模型入口。适合谁看正在用 SAP CAP 做 BTP side-by-side 扩展、Fiori Elements 应用、S/4HANA Cloud 扩展的后端或全栈开发者已经在用 Claude Code 或 Cline 写 CAP 代码但感觉 Agent 老是理解偏的人以及想把团队 Agent 配置统一进 Git 仓库的技术负责人。2. TaoToken 前置给 Claude Code 一个统一的模型通道在讲.mcp.json之前得先把 Claude Code 本身的模型通道说清楚。因为.mcp.json解决的是“Agent 能不能读懂 CAP 项目”而 TaoToken 解决的是“Agent 背后的模型请求走哪里”。这两件事是叠加关系不是替代关系。Claude Code 默认会走 Anthropic 官方通道。但在实际团队开发里经常遇到几个现实问题多人协作时每个人的 key 管理分散想在 Claude Code 里切换不同模型做对比或者需要把请求统一到一个可控的入口做审计和配额管理。TaoToken 在这里的角色就是一个统一的模型接入通道提供兼容 Anthropic 风格的 API 入口Claude Code、Cline、Codex 这类工具都可以把 Base URL 指过来。你需要先拿到两样东西一个 API Key以及确认要用的 Model ID。API Key 在控制台的 API Keys 页面创建地址是https://taotoken.net/api-keys。创建时建议按项目或按人命名比如cap-claude-code-dev方便后面排查是谁的请求。Model ID 这块要注意Claude Code 走的是 Anthropic 兼容协议所以模型名要填 Anthropic 风格的 ID比如claude-sonnet-4-5这类。具体可用列表以控制台和文档为准不要凭记忆写。文档入口在https://taotoken.net/doc里面有各客户端的接入说明。这里有个容易踩的坑很多人把 TaoToken 的 API Base URL 写成https://taotoken.net/api但在 Claude Code 的环境变量里通常需要的是带版本路径的完整 base比如https://taotoken.net/api不加 UTM具体以文档为准。写错路径最常见的表现就是 401 或者 404而不是模型报错。另外提醒一句TaoToken 是模型接入通道不是 CAP 运行时的一部分也不替代任何编辑器或 IDE。它只负责把 Claude Code 发出的模型请求转到一个统一入口。.mcp.json里的cap-js/mcp-server是本地进程和 TaoToken 的模型通道是两条独立的链路一个走 stdio 本地通信一个走 HTTPS 到模型服务。如果你只是想让 Claude Code 能读懂 CAP 项目.mcp.json配好就够了。如果你还想让模型请求统一管理、方便切换模型、团队共用配额那就把 Claude Code 的 Base URL 和 Key 改到 TaoToken。两件事可以分开做也可以一起做。3. 可复制配置.mcp.json 与 Claude Code 通道设置这一节给两份可直接复制的配置。第一份是项目根目录的.mcp.json第二份是 Claude Code 走 TaoToken 的 settings 片段。两份都按真实路径和字段写你改掉 Key 就能用。先看.mcp.json。注意顶层必须是mcpServers这是 Claude Code project scope 的标准结构。SAP 官方cap-js/mcp-server仓库的示例也是这个结构只是 server 名字常用cds-mcp。我这里用sap-cap-capire作为名字你可以改成任何你喜欢的别名名字本身不影响能力。{ mcpServers: { sap-cap-capire: { command: npx, args: [-y, cap-js/mcp-server], env: {} } } }逐字段说明。command是npx表示客户端会在本地执行 npx 命令而不是去连一个远程服务。args里的-y是让 npx 在需要安装或确认时自动同意cap-js/mcp-server是要运行的包。env是空对象说明这个 server 启动时不注入额外环境变量。这一点在企业项目里很重要——空 env 意味着它没有显式携带业务凭据更像一个本地 CAP 项目理解器和文档检索器而不是直连生产系统的远程执行器。如果你希望锁定版本避免团队成员不同时间拿到不同版本可以把 args 改成{ mcpServers: { sap-cap-capire: { command: npx, args: [-y, cap-js/mcp-server1.0.0], env: {} } } }版本号以 npm 上实际发布的为准别照抄我这里的示例号。企业交付项目建议锁版本个人学习项目用 latest 更方便。接下来是 Claude Code 走 TaoToken 的配置。Claude Code 读取的是 settings 文件通常在~/.claude/settings.json用户级或项目级.claude/settings.json。里面通过env注入ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三件套对应关系要记牢Base URL 填 TaoToken 的 API 入口Key 填你在https://taotoken.net/api-keys创建的 tokenModel ID 填 Anthropic 风格的模型名。这三个字段任何一个写错表现都不一样——Base URL 错通常是连接失败或 404Key 错是 401Model ID 错是模型不存在或 reading choices 类报错。如果你用的是 Cline 或 Codex配置位置不同但三件套一样。Cline 在 MCP 配置里用mcpServers根节点模型通道在 Cline 的 API 配置里填 Base URL 和 Key。Codex 走auth.json里面填 API Key 和 base URL。不管哪个客户端Base URL、Key、Model ID 这三样必须齐全且一致。还有一个细节.mcp.json支持环境变量展开可以在command、args、env、url、headers里用${VAR}形式引用环境变量。团队共享配置时不要把 Key 硬编码进.mcp.json而是通过本机环境变量或 secret manager 注入。这样.mcp.json可以安全提交进 GitKey 留在每个人本地。4. 验证请求确认 MCP 加载成功且 CDS 上下文可读配置写完不等于生效。这一节给一套可跟做的验证动作从 MCP server 加载到 CDS 上下文读取再到模型通道连通性一步步确认。第一步确认.mcp.json被 Claude Code 识别。在项目根目录启动 Claude Code然后输入/mcp命令或者另开终端执行claude mcp list。如果配置正确你应该能在列表里看到sap-cap-capire状态显示 connected。如果看不到这个名字先检查.mcp.json是否在项目根目录以及顶层是否有mcpServers节点。裸顶层直接写 server 名字的写法Claude Code 不一定识别。第二步确认 MCP server 进程真的起来了。Claude Code 在首次使用 project scope 的 MCP server 时会要求你批准这是安全机制。批准后npx -y cap-js/mcp-server会作为子进程启动通过 stdio 和客户端交换 JSON-RPC 消息。你可以在另一个终端执行ps aux | grep mcp-server看进程是否存在。如果进程反复退出多半是 npx 拉包失败或 Node 版本不满足要求。第三步验证 CDS 上下文可被读取。这一步不要问泛泛的 CAP 概念要问只有 CAP MCP server 才适合回答的问题。比如在 Claude Code 里输入“帮我查一下当前项目里有哪些 CDS service 对外暴露它们的 endpoint 分别是什么。”如果 Agent 明确调用了search_model工具并给出和编译模型一致的结果说明 MCP server 正在发挥作用。再问“CAP Node.js 里给 service handler 加自定义 action 的正确写法是什么”如果它先通过search_docs查官方文档再回答说明文档检索也通了。第四步验证 TaoToken 模型通道。这一步和 MCP 无关单独测。在 Claude Code 里随便问一个需要模型推理的问题比如“用一句话解释 CDS 里 projection 和 entity 的区别”。如果正常返回说明 Base URL、Key、Model ID 三件套都对。如果报 401检查 Key 是否复制完整、是否有多余空格。如果报连接失败检查 Base URL 是否写成了https://taotoken.net/api且没有多余路径。第五步做一个端到端验证。让 Claude Code 完成一个需要同时用到 CAP 上下文和模型推理的任务比如“在当前 CAP 项目里给某个 service 增加一个只读 projection并说明这个 projection 会暴露哪些字段。”观察它的行为先查 model 确认 service 和 entity 结构再查文档确认语法最后生成代码。整个过程如果顺畅说明.mcp.json和 TaoToken 通道都在正常工作。实测下来最容易出问题的不是配置本身而是路径和版本。.mcp.json放错目录、Node 版本太老导致 npx 拉包失败、Base URL 多写或少写路径这三类占了大部分验证失败。建议每改一次配置就重新跑一遍/mcp和一次模型问答别攒着一起调。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来对照排查。每个报错先给现象再给原因最后给动作。你遇到哪个就查哪个。401 Unauthorized。现象是 Claude Code 发请求后返回 401或者提示 authentication failed。原因通常是 TaoToken 的 Key 写错、过期、或者复制时带了换行和空格。动作去https://taotoken.net/api-keys重新创建一个 Key复制时确认没有多余字符然后更新 settings 里的ANTHROPIC_AUTH_TOKEN。如果用的是环境变量引用确认变量名拼写一致。还有一种情况是 Base URL 写成了别的路径导致请求打到了不需要鉴权的端点也会表现异常。local proxy failed / connection refused。现象是 Claude Code 提示本地代理失败或连接被拒。原因通常是 Base URL 指向了一个本地不存在的代理端口或者网络环境导致 HTTPS 请求发不出去。动作确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要填localhost或某个本地端口。如果你之前配过其他工具的代理设置检查是否残留了冲突的环境变量。reading choices / choices 字段报错。现象是返回体解析失败提示 reading choices 或类似字段缺失。原因通常是 Model ID 写错或者 Base URL 指向了一个 OpenAI 风格的端点而不是 Anthropic 风格端点。动作确认ANTHROPIC_MODEL填的是 Anthropic 风格模型名确认 Base URL 是 Anthropic 兼容入口。TaoToken 的文档里有各协议的入口说明对照https://taotoken.net/doc检查。OAuth / authentication flow 报错。现象是提示需要 OAuth 登录或 token 刷新失败。原因通常是 Claude Code 还在尝试走官方 OAuth 流程而不是用你配置的 API Key。动作确认 settings 里用的是ANTHROPIC_AUTH_TOKEN而不是 OAuth 相关字段。如果你之前登录过官方账号可能需要清理旧的凭据缓存让 Claude Code 走 API Key 模式。MCP server 显示 failed 或 disconnected。现象是/mcp列表里sap-cap-capire状态不是 connected。原因可能是.mcp.json结构不对、npx 拉包失败、Node 版本不满足、或者项目根目录不对。动作先确认顶层是mcpServers再在终端手动执行npx -y cap-js/mcp-server看是否能启动。如果手动执行也失败看报错是网络问题还是 Node 版本问题。如果手动能启动但 Claude Code 里不行检查.mcp.json是否在 Claude Code 启动时的工作目录下。CDS 上下文读不到。现象是 MCP server 连上了但 Agent 回答 CAP 问题时还是靠猜。原因可能是项目本身 CDS 编译失败或者 Agent 没有优先调用 MCP 工具。动作先在终端跑cds compile srv --to csn确认项目能编译。然后在项目里加一个AGENTS.md写明“搜索 CDS definitions 时优先使用 cds-mcp创建或修改 CDS models 时先搜索 CAP docs”。SAP 官方 README 也建议这么做能显著提升 Agent 调用 MCP 工具的概率。Key 泄露风险。现象是.mcp.json或 settings 里硬编码了 Key然后提交进了 Git。动作立刻去控制台吊销旧 Key重新创建改用环境变量引用。.mcp.json支持${VAR}展开settings 也支持环境变量团队共享配置时只提交不含密钥的模板。排查顺序建议先确认模型通道通问一个普通问题再确认 MCP 通道通问一个 CAP 模型问题最后确认两者协同问一个需要两者配合的任务。这样能把问题定位到具体链路不用来回猜。6. 把配置沉淀进团队仓库让 CAP 智能开发可复制走到这里你已经有了可复制的.mcp.json、可复制的 Claude Code 通道配置、一套验证动作和一份报错对照表。接下来最有价值的一步是把这些东西沉淀进团队仓库让每个成员拉下来就能用。具体做法是项目根目录提交.mcp.json里面只放 server 定义不放任何 Key。Claude Code 的 settings 模板可以放在.claude/settings.example.json里面用环境变量占位成员复制成.claude/settings.json后填入自己的 TaoToken Key。再写一份简短的AGENTS.md说明这个项目里 Agent 应该优先用 CAP MCP server 查模型和文档以及模型通道走 TaoToken 的统一入口。这样做的收益很直接。新成员加入时不用自己摸索 MCP 配置拉代码、填 Key、启动 Claude Code就能获得一个懂 CAP 模型的 Agent。团队里每个人的 Agent 行为一致减少“我这边能跑你那边不行”的扯皮。模型请求统一走 TaoToken配额和审计也有据可查。如果你还想进一步可以把 Claude Code 的长期编码和 Agent 任务统一到 Coding Plan 上入口在https://taotoken.net/coding-plan。模型对话类的快速验证走https://taotoken.net/chat。API Key 管理在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc。Claude Code 相关的 Anthropic 接入说明在https://taotoken.net/claude-code-anthropic。最后留一个实用技巧每次升级cap-js/mcp-server版本后重新跑一遍第 4 节的五步验证。因为 MCP server 的工具名和行为可能随版本变化Agent 的调用方式也可能受影响。锁版本的项目在升级前先在分支上验证确认search_model和search_docs都正常再合并。这样能把工具升级带来的不确定性挡在主干之外。