1. 为什么要把 Agent Builder 工具暴露给任意 AI agent如果你正在用 Elasticsearch 做内部知识库、日志分析或者安全告警查询大概率已经踩过一个坑工具逻辑写在 Elastic Agent Builder 里但日常写代码用的是 Cursor、VS Code、Claude Code两边割裂。每次想让编辑器里的 AI 帮忙查一条内部文档都得手动切到 Kibana 界面复制粘贴效率极低。Elastic MCP 服务器解决的正是这个问题。MCPModel Context Protocol是一个开放标准让 AI agent 能够发现并调用外部工具。Elastic Agent Builder 内置了 MCP 服务器会把你在 Agent Builder 里定义的自定义工具通过一个安全的 MCP 端点标准化暴露出来。任何兼容 MCP 的客户端——Cursor、VS Code、Claude Desktop、Cline——都能直接发现并调用这些工具。换句话说你在 Agent Builder 里写一次工具所有 agent 都能复用。这就是“工具复用”和“多 agent 协作”的核心价值。适合谁三类人最需要一是把内部工程文档索引进 Elasticsearch、想让编辑器 AI 直接查的开发者二是做可观测性、想让 agent 帮忙分析日志的 SRE三是搭多 agent 系统、需要统一工具注册中心的架构同学。但这里有个现实问题多个 agent 各自配置 Elastic API Key权限管理会变得很乱。我的做法是通过 TaoToken 统一 Key 和 API 通道把鉴权和联调收敛到一个入口后面会给出具体配置。这篇内容我会按“建工具 → 配 MCP 服务端 → agent 侧调用 → 排障”的顺序走一遍每一步都给可复制的配置片段。2. Elastic MCP 服务器与 TaoToken 前置准备在动手配置之前先把两件事理清楚Elastic 侧要准备什么TaoToken 侧要准备什么。Elastic 侧你需要三样东西。第一是一个可访问的 Elasticsearch 集群本地跑或者云上都行里面要有你想暴露的数据索引。第二是 Kibana 里的 Agent Builder 权限能创建工具。第三是一个 Elasticsearch API Key这个 Key 决定了 MCP 工具能访问哪些索引、执行哪些操作——权限最小化原则在这里很重要别用超级用户 Key。创建 ES API Key 的路径在 Kibana 的 Stack Management → Security → API Keys。创建时把权限范围限定到你实际要查询的索引比如只给elastic-dev-docs的read权限。这样即使 Key 泄露影响面也可控。TaoToken 侧的作用是统一鉴权和 API 通道。当你同时接多个 agentCursor 一个、Claude Code 一个、Cline 一个如果每个都单独配 Elastic Key轮换和审计会很痛苦。TaoToken 提供一个统一的 Key 管理和 API 入口你可以在控制台里创建 Key、查看调用记录、按项目分配额度。具体操作访问 TaoToken 控制台在 API Keys 页面创建一个新 Key。这个 Key 后面会作为 agent 侧调用模型和工具的鉴权凭证。如果你用的是 Coding Plan 场景长期编码和 Agent 任务建议直接走 Coding Plan额度和稳定性更适合高频调用。模型选择上工具调用对模型的 function calling 能力有要求。实测下来Claude 系列和 GPT 系列在 MCP 工具发现和参数填充上表现稳定。你可以在模型对话页面先验证一下模型是否能正确识别工具描述。这里要强调一个概念Elastic MCP 服务器暴露的是“工具”不是“agent”。Agent Builder 里的 agent 和通过 MCP 暴露的工具是分开的。MCP 是“自带工具”模式让你现有的编辑器 agent 获得访问私有数据的能力。如果你需要完整的自定义 agent 之间互相委托那是 A2A Protocol 的范畴别混用。前置准备清单项目来源用途Elasticsearch 集群本地或云存放待查询数据ES API KeyKibana SecurityMCP 工具鉴权Agent Builder 工具Kibana Agent Builder定义查询逻辑TaoToken API KeyTaoToken 控制台统一 agent 侧鉴权MCP 客户端Cursor/VS Code 等调用工具把这几样准备好后面的配置就是填空。3. 可复制的 MCP 服务端与 agent 配置片段这一节是核心给出可直接复制的配置。分两部分Elastic MCP 服务端侧工具注册和 agent 侧MCP 客户端配置。先说工具注册。在 Kibana 的 Agent Builder 里新建一个工具工具描述非常关键因为 agent 就是靠描述来决定调不调用你的工具。描述要具体包含索引名和用途。比如Performs a semantic search on the elastic-dev-docs index to find internal engineering documentation, runbooks, and release procedures.保存后Elastic 会自动通过 MCP 端点暴露这个工具。端点 URL 在 Kibana 的 Tools UI 里能找到格式类似https://your-kibana.kb.company.io/api/agent_builder/mcp接下来是 agent 侧的 MCP 配置。以 Cursor 为例编辑~/.cursor/mcp.json{ mcpServers: { elastic-agent-builder: { command: npx, args: [ mcp-remote, https://your-kibana.kb.company.io/api/agent_builder/mcp, --header, Authorization:${AUTH_HEADER} ], env: { AUTH_HEADER: ApiKey ELASTIC_API_KEY } } } }注意AUTH_HEADER里的ApiKey前缀不能少后面跟你的 ES API Key。这个配置用的是mcp-remote这个 npm 包做桥接所以本地要有 Node.js 环境。如果你用的是 Claude Code配置方式不同走的是settings.json或者项目级配置。Claude Code 的 MCP 配置片段{ mcpServers: { elastic-agent-builder: { type: http, url: https://your-kibana.kb.company.io/api/agent_builder/mcp, headers: { Authorization: ApiKey ELASTIC_API_KEY } } } }Cline 的配置在 VS Code 的 settings 里走 MCP Servers 面板填入同样的 URL 和 Authorization header 即可。现在说 TaoToken 的接入。如果你希望多个 agent 共用一套鉴权通道可以在 agent 的模型配置里把 Base URL 指向 TaoToken 的 API 端点Key 用 TaoToken 控制台创建的 Key。这样模型调用和工具调用都经过统一通道审计和额度管理都在一处。三件套配置Base URL Key Model ID示例Base URL: https://taotoken.net/api API Key: 你的 TaoToken Key Model ID: claude-sonnet-4-5 (或你实际使用的模型)把这三样填到 Cursor 的模型设置、Claude Code 的环境变量、或者 Cline 的 provider 配置里。注意 Base URL 不要加多余路径直接是https://taotoken.net/api。配置完成后重启你的编辑器或 MCP 客户端让配置生效。4. 验证请求与成功结果确认配置写完不代表能用必须验证。验证分三层MCP 连接是否建立、工具是否被发现、工具调用是否返回正确结果。第一层检查 MCP 连接。在 Cursor 里打开 MCP 面板应该能看到elastic-agent-builder这个 server 状态是绿色或 connected。如果显示红色或 error先看下一节的排障。Claude Code 里可以用/mcp命令查看已连接的 server 列表。第二层确认工具被发现。在 Cursor 的 MCP 面板展开elastic-agent-builder应该能看到你在 Agent Builder 里注册的工具名比如engineering_documentation_internal_search。如果工具列表是空的说明 MCP 端点连上了但工具没暴露出来回去检查 Agent Builder 里工具是否保存成功、是否处于启用状态。第三层实际调用。在 Cursor 的 chat 里提一个需要查内部文档的问题比如Lookup steps to release crawler service from engineering internal documentation正常情况下Cursor agent 会判断需要调用工具然后调用engineering_documentation_internal_search传入自然语言查询参数。工具对elastic-dev-docs索引执行语义搜索返回最相关的文档片段。你会在 chat 里看到工具调用的过程展示以及最终基于内部文档生成的答案。如果一切正常你会看到类似这样的调用链路agent 决定调用工具 → 工具返回检索结果 → agent 基于结果生成回答。整个过程不需要你离开编辑器。验证 TaoToken 通道是否生效可以在 TaoToken 控制台的调用记录里看到对应的请求。如果记录里有请求且状态正常说明统一通道工作正常。一个实测细节语义搜索的效果取决于索引里的数据质量和 embedding 模型。如果返回结果不相关先检查索引是否用了合适的 embedding而不是怀疑 MCP 配置。验证通过后你可以把这套配置复制到其他 agent。因为工具是标准化暴露的同一个 MCP 端点可以被多个客户端同时连接互不干扰。5. 本篇常见错误排查配置过程中最容易踩的坑集中在鉴权、网络和工具发现三个环节。下面按真实报错对照排查。401 Unauthorized。这是最常见的。原因通常是 ES API Key 无效、过期或者Authorizationheader 格式不对。检查两点一是ApiKey前缀和 Key 之间有一个空格二是 Key 本身没有多余换行。如果你用的是 TaoToken 通道确认 TaoToken Key 没有超出额度或被禁用。local proxy failed / connection refused。这个报错通常出现在mcp-remote桥接场景。原因是本地 Node 环境缺失或者npx无法拉取mcp-remote包。解决办法确认node -v能正常输出版本然后手动跑一次npx mcp-remote --help看是否能下载。如果公司网络限制 npm需要配置 npm 镜像源。reading choices of undefined。这个报错一般出现在模型调用层不是 MCP 层。原因是模型返回结构不符合预期常见于 Base URL 配错或者 Model ID 写错。检查 TaoToken 的 Base URL 是否是https://taotoken.net/apiModel ID 是否是控制台里实际可用的模型。如果 Base URL 多写了/v1之类的路径会导致返回结构异常。OAuth 相关报错。如果你用的是 Claude Code 且配置了 OAuth 类型的 MCP server报错通常和 token 刷新有关。Elastic MCP 用的是 API Key 鉴权不需要 OAuth所以配置里type应该是http而不是oauth。改对类型即可。工具列表为空。MCP 连上了但看不到工具。排查顺序Agent Builder 里工具是否保存并启用 → MCP 端点 URL 是否指向正确的 Kibana 空间 → ES API Key 是否有权限读取该工具。有时候工具创建了但没发布需要手动确认状态。调用工具返回空结果。工具被调用了但没返回数据。这通常是索引里没有匹配内容或者语义搜索的 embedding 不匹配。先用 Kibana 的 Dev Tools 直接对索引跑一次查询确认数据存在。排障时建议打开 MCP 客户端的日志。Cursor 的 MCP 日志在输出面板里能切到Claude Code 用--debug启动能看到详细请求。日志里会显示实际的请求 URL 和 header对照检查最快。如果鉴权问题反复出现建议统一走 TaoToken 的 API Keys 管理把 Key 轮换和权限收敛到一个地方减少多 agent 各自配置带来的混乱。接入文档里有完整的鉴权说明。6. 多 agent 复用与统一通道的落地建议把工具暴露出来只是第一步真正提升效率的是让多个 agent 稳定复用同一套工具和鉴权。我的建议是分层管理。工具层由 Elastic Agent Builder 统一注册所有查询逻辑写在这里改一次所有 agent 生效。鉴权层由 TaoToken 统一管理所有 agent 的模型调用和工具调用走同一个 Key 通道额度、审计、轮换都在控制台完成。客户端层各自配置 MCP 端点但指向同一个 URL。这样做的直接好处是新接一个 agent 只需要复制 MCP 配置片段不用重新申请 Elastic Key也不用重新定义工具。对于多 agent 协作场景工具注册中心是共享的agent 之间不会出现“这个工具只有那个 agent 能用”的碎片化问题。长期跑编码和 Agent 任务的话Coding Plan 在额度和稳定性上更适合高频调用比按次计费更划算。你可以先在模型对话页面验证工具调用链路确认无误后再切到 Coding Plan 做长期任务。最后给一个实用技巧把 MCP 配置片段和 TaoToken 三件套Base URL、Key、Model ID写进项目的 README 或者团队 wiki新同学接入时直接复制省去反复排查鉴权的时间。工具描述也建议统一模板包含索引名、用途、返回内容类型这样 agent 选择工具的准确率会明显提升。