想让btca MCP为你的 Cursor、Claude Code 或 Codex 提供"基于真实源码"的上下文吗？better-context（btca）是一个开源的上下文工具，它的核心思路是：不去相信过时的文档，而是直接搜索库和框架的真实源代码来回答你的问题。通过 MCP（Model Context Protocol），btca 可以把listResources和ask两个工具暴露给你的编码代理，让 AI 在写代码时随时查到最新、最准确的 API 用法。本文带你完整走完本地 MCP与云端 MCP两种接入模式，5 分钟配好三大主流编码工具。

两种接入模式怎么选？🤔

btca 的 MCP 接入分为两种模式，先搞清楚区别再动手，可以少走弯路：

💡 官方文档中对两种模式的说明见 mcp.mdx；本地 MCP 的自动脚手架实现在 mcp.ts。

本地 MCP 最快配置方法：安装并初始化 btca

本地模式完全跑在你自己的电脑上，前提是先装好 btca CLI（需要 Bun 运行时，若没有 Bun 也可以用npm add -g btca代替）：

# 1. 全局安装 btca bun add -g btca # 2. 在项目中初始化，生成 btca.config.jsonc btca init # 3. 添加要检索的资源（git 仓库 / 本地目录 / npm 包均可） btca add -n svelte https://github.com/sveltejs/svelte btca add npm:react@19 -n react -t npm # 4. 连接一个 AI Provider（本地问答由它驱动） btca connect --provider opencode --model claude-haiku-4-5 # 5. 验证资源已就位 btca resources

配置细节（provider、model、resources等字段）参考 configuration.mdx 和示例配置 example-AGENTS-section.md。

装好后可以先在终端里体验一下btca ask，确认资源能正常回答再接入编辑器。

一键安装步骤：把 btca MCP 写入 Cursor

Cursor 支持两种传输方式，在.cursor/mcp.json中选择其一即可。

方式一：本地 stdio（推荐新手）

{ "mcpServers": { "btca-local": { "command": "bunx", "args": ["btca", "mcp"] } } }

方式二：云端 HTTP

{ "mcpServers": { "btca-cloud": { "url": "https://btca.dev/api/mcp", "headers": { "Authorization": "Bearer ak你的API_KEY" } } } }

⚡ 偷懒技巧：直接运行btca mcp local，它会交互式询问你要配置哪个编辑器（Cursor / Claude Code / Codex / OpenCode），然后自动写好对应的配置文件，见 mcp.ts 中的编辑器列表。

Claude Code 接入：两条命令搞定

Claude Code 通过命令行注册 MCP server，本地与云端各一条命令：

# 本地模式（stdio） claude mcp add --transport stdio btca-local -- bunx btca mcp # 云端模式（HTTP，把 ak... 换成你的 API Key） claude mcp add --transport http better-context https://btca.dev/api/mcp \ --header "Authorization: Bearer ak..."

执行后在 Claude Code 会话中输入/mcp可以查看连接状态，确认btca-local或better-context显示为已连接即可。

Codex 接入：config.toml 配置指南

Codex 的 MCP 配置写在config.toml中。

云端模式—— 编辑 Codex 的config.toml（例如~/.codex/config.toml），并把 API Key 放入环境变量（如.zshenv中加export BTCA_API_KEY=ak...）：

[mcp_servers.btca] bearer_token_env_var = "BTCA_API_KEY" enabled = true url = "https://btca.dev/api/mcp"

本地模式—— 一条 CLI 命令：

codex mcp add btca-local -- bunx btca mcp

如上图，接入成功后 Codex 会在你提问时自动先调用listResources查看可用资源，再用ask基于指定资源检索真实源码。

让 AI 自动"会查"：把用法写进 AGENTS.md

MCP 接好了，但代理不一定知道什么时候该用。最佳实践是在项目的AGENTS.md中追加一段使用指引（Cursor、Claude Code、Codex 都会读取它）：

# btca MCP Usage Instructions Use btca whenever a task depends on understanding a repo or a configured resource more accurately than a generic model can. - Always call `listResources` FIRST before using `ask`. - `ask` requires exact resource names from the list (e.g. "svelteKit", not "SvelteKit"). - If a needed resource is missing, proceed without btca and note it clearly when done.

这段模板直接来自官方文档 mcp.mdx，核心就一条铁律：先listResources，再ask，资源名必须与列表完全一致。

常见问题速查 🧭

总结

• 本地模式：btca init+btca add+bunx btca mcp，零 API Key、数据不出本机，适合个人与私有仓库；
• 云端模式：填入 btca 控制台获取的 API Key，指向https://btca.dev/api/mcp，适合团队共享资源；
• 一键配置：btca mcp local可为 Cursor、Claude Code、Codex、OpenCode 自动生成配置文件；
• 收尾动作：在AGENTS.md中写入"先 list 后 ask"的工作流，AI 才会主动用它。

更多命令细节可查看 cli-reference.mdx、quickstart.mdx，以及供 AI 代理使用的 btca 技能文件 SKILL.md。配置完成后，你的编码代理就拥有了"查源码"的超能力，再也不必为过时的文档而困惑了。