企业官网建设流程全解析

1. 为什么要把 Agent Builder 工具暴露给任意 AI agent

如果你正在用 Elasticsearch 做内部知识库、日志分析或者安全告警查询，大概率已经踩过一个坑：工具逻辑写在 Elastic Agent Builder 里，但日常写代码用的是 Cursor、VS Code、Claude Code，两边割裂。每次想让编辑器里的 AI 帮忙查一条内部文档，都得手动切到 Kibana 界面复制粘贴，效率极低。

Elastic MCP 服务器解决的正是这个问题。MCP（Model 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 通道。当你同时接多个 agent（Cursor 一个、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 的范畴，别混用。

前置准备清单：

把这几样准备好，后面的配置就是填空。

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/api，Model 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 选择工具的准确率会明显提升。