> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# MCP 操作

> 连接并验证 MCP 操作，同时清楚区分服务器凭据、最终用户授权和运行时工具调用。

MCP 操作让智能体能够使用 MCP 服务器公开的工具。管理员可以管理全部服务器；内容管理员可以创建服务器，但只能维护自己创建的服务器。最终用户只授权自己收到的访问提示，运行时只调用已保存操作配置中的工具。

## 上线前检查

MCP Action 的风险通常来自工具过宽、凭据过强或返回内容不可控。上线前请逐项确认：

| 检查项      | 要求                                       |
| -------- | ---------------------------------------- |
| 工具范围     | 只选择目标 Agent 必需的工具，不把整组管理工具直接暴露给通用 Agent。 |
| 凭据权限     | 服务凭据只具备完成该工具调用所需的最小权限。                   |
| 用户授权     | 高影响操作必须让最终用户看到明确授权提示。                    |
| 错误处理     | 工具失败时返回可理解的错误，不把密钥、header 或内部堆栈暴露给用户。    |
| 维护 owner | 明确谁负责服务器地址、密钥轮换、工具变更和下线。                 |

## MCP 操作的工作方式

MCP 服务器会发布一个或多个可供 Agent 使用的工具。艾维斯读取已配置服务器提供的工具，由 Admin 或拥有该服务器的 Curator 选择哪些工具属于某个 Action。只有在 Agent 配置和当前运行均允许时，Agent 才能使用这些选定工具。

## 添加 MCP 服务器

1. 以管理员或内容管理员身份登录并打开“MCP 操作”。
2. 使用部署的受保护配置字段添加已批准的 MCP 服务器。
3. 检查从服务器发现的工具，只选择目标 Agent 工作流所需的工具。
4. 保存 Action，将它附加到 Agent，并在检查后再发布 Agent。

Admin 可以创建或变更任意 MCP 服务器、选择工具、完成受保护配置，并将 Action 附加到任意可编辑 Agent。Curator 可以创建 MCP 服务器，但只能变更自己创建的服务器。该所有权规则对 Curator 和 Global Curator 完全相同；Action 所有权不会从其负责群组或所属群组继承。

服务器所有者应记录预期工具和运行限制。请将 Action 的范围保持在较小范围内，让已配置工具与 Agent 用途一致。所有权只约束创建后的变更、删除和受保护凭据维护。

Curator 可以把当前可用的任意 MCP Action 附加到自己有权编辑的 Agent。部署级模型、集成、安全、Index Settings、Usage 和组织配置仍由 Admin 负责。

## 认证职责

只能通过 Admin 或服务器所有者可访问的受保护 Action 设置配置服务器认证。不要将密钥放入 Agent 指令、最终用户消息、源代码管理或共享文档中。

服务器所有者负责配置和轮换服务凭据；Admin 也可以维护这些凭据。最终用户授权一次 Action 运行并不会获得这些凭据，也不能借此授权重新配置 MCP 服务器。

## 验证工具

Admin 或拥有该服务器的 Curator 应先确认保存服务器后预期工具会显示。然后使用有代表性且已获批准的请求运行已附加的 Agent，确认调用预期工具、结果可用，并确认共享范围以外的最终用户无法访问该 Agent。

运行时，请检查报告的工具结果或错误，而不要假定工具一定可用。调用无法运行时，请重新检查服务器连接、所选工具、Agent 附加关系和适用的最终用户授权。

## 排查问题

如果工具未显示，请确认服务器配置完整，且服务器能够向该部署公开工具。如果工具存在但在运行时失败，请检查其服务端权限和服务器允许的输入。

如果最终用户无法使用原本正常的 Action，请先检查 Agent 的共享范围和任何授权提示，再更改服务器配置。每次变更后均使用已批准请求重新测试。

## 相关页面

* [管理 Agent](/aivis/agents/agents) 介绍如何将 MCP Action 附加到 Agent。
* [OpenAPI 操作](/aivis/agents/openapi-actions) 介绍具有相同访问边界的 API 支持型操作。
* [模型凭据](/aivis/models/model-credentials) 介绍模型服务的受保护凭据。