MCP 集成

你的知识库能回答那些你已经写下来的问题。而 MCP 服务器让 Minaya 能够在对话过程中调用你自己的系统，回答那些会变化的问题—— 订单状态、库存水平、预订可用情况。

什么是 MCP

Model Context Protocol 是一个向 AI 系统暴露工具的开放标准。你运行一个声明一组工具的服务器；Minaya 作为客户端连接，发现有哪些可用工具，并由模型决定何时调用其中之一。

Minaya 通过 Streamable HTTP 连接到远程 MCP 服务器。不支持本地 stdio 服务器——服务器必须能从公网访问。

调用是如何进行的

访客提出问题。
Minaya 照常检索相关内容片段。
已启用的 MCP 服务器提供的工具会与该上下文一并提交给模型。
如果模型调用某个工具，Minaya 会连接到你的服务器并执行它。
结果会被回传，模型据此作答。

工具调用会在回复开始流式输出前完成，因此访客看到的是一个干净的完整答案，而不是中间步骤。

套餐

连接 MCP 服务器属于专业版和企业版。在其他套餐中，集成页面会显示升级提示，无法添加新服务器，已连接的服务器也不会在对话中使用。

使用 Minaya 的 AI 时，调用工具的回复会从您的额度中计为 3 条消息；使用您自己的密钥时计为 1 条。参见套餐与计费。

当知识库没有答案时

即使知识库中没有任何内容与问题匹配，也会提供工具。助手会被告知这些工具连接的是您的账户——因此“列出仓库”指的是您的仓库——并在合适时调用工具。只有当没有合适的工具时，它才会回复您的兜底消息。它从不根据通用知识作答。

如果工具需要访客未提供的信息（例如哪个仓库），助手会询问。

拥有 MCP 服务器的企业，其回复从不使用答案缓存：回复可能依赖实时数据，缓存的回复会过时。

连接服务器

前往集成并添加：

字段	说明
名称	供你自己参考的标签，例如“订单查询”。
服务器 URL	通过 Streamable HTTP 提供 MCP 的公开 HTTPS 端点。
Bearer 令牌	可选。静态加密存储，保存后不再显示。

Minaya 会立即探测该服务器，并显示找到的工具数量，或在无法连接时显示错误信息。可随时使用测试重新探测。

优先使用只读权限

网站的任何访客都可以要求助手使用提供给它的任何工具。请只为服务器和令牌授予访客应有的权限——尽可能只读。当服务器提供的工具超出上限（见下方限制）时，优先保留只读工具，优先舍弃会修改数据的工具。

限制

限制项	数值	原因
每个企业的服务器数量	5	每条消息都会产生发现延迟成本。
每个会话的工具调用次数	10	限制成本并防止失控循环。
每条消息的轮次	2	足以分两步查询信息，但不能无限进行。
每轮工具数	2	同一步中的其他调用会被跳过，模型可以再次请求。
提供的工具定义	约 12,000 个字符	每个定义都会随每次请求发送。服务器提供更多时，优先保留只读工具。
工具结果	3,000 个字符	更长的结果会在模型读取前被截断。
额度消耗	3 条消息	使用 Minaya 的 AI 时，每条调用工具的回复计 3 条；使用您自己的密钥时计 1 条。
连接超时	8 秒	缓慢的服务器不能让访客的对话卡住。
工具调用超时	15 秒	绝对上限为 20 秒。

如果服务器无法访问，对话会继续仅使用你的知识库——MCP 故障不会中断聊天。

构建服务器

任何 MCP 服务器实现都可以使用。以下是使用 TypeScript SDK 的最小示例：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "orders", version: "1.0.0" });

server.tool(
  "get_order_status",
  "Look up the delivery status of an order by its reference.",
  { orderId: z.string().describe("The customer's order reference") },
  async ({ orderId }) => {
    const order = await db.orders.findByReference(orderId);
    if (!order) {
      return { content: [{ type: "text", text: "No order with that reference." }] };
    }
    return {
      content: [{
        type: "text",
        text: `Order ${orderId}: ${order.status}, expected ${order.eta}.`,
      }],
    };
  },
);

通过 Streamable HTTP 暴露它，并把 URL 提供给 Minaya。

设计好的工具

清楚地描述它们。 描述文字是模型判断是否调用某个工具的依据。“按订单编号查询配送状态”比“订单接口”更好。
参数要少且命名清晰。 模型会从对话中填充参数，因此 orderId 比 q 效果更好。
返回文字叙述，而非原始 JSON。 结果会进入模型的上下文；可读的句子比转储的对象能产生更好的答案。
处理空结果的情况。 返回“未找到订单”而不是错误，这样模型才能向访客解释。
保持快速响应。 访客在等待；超过 15 秒的调用会被中断。

安全性

由于你提供的 URL 会被 Minaya 的服务器调用：

私有地址会被阻止。 环回地址、私有网段、链路本地地址、CGNAT 以及云元数据端点均会被拒绝——在你保存时以及每次连接前都会重新校验，因此 DNS 变更无法绕过这一限制。
生产环境中必须使用 HTTPS。
令牌以静态加密方式存储，且 API 永远不会返回它。
工具元数据被视为不可信内容。 被攻陷的服务器可能会在工具名称或描述中隐藏指令，因此元数据会被清理，含有类指令文本的工具会被丢弃。
结果被标记为数据。 工具输出会被包装，使模型将其视为信息，而绝不当作指令。

其余内容参见安全性。

管理服务器

切换开关——无需删除即可停用；已停用的服务器不会提供给模型。
测试——重新探测并刷新工具数量。
删除——移除该服务器及其已保存的令牌。

作为 MCP 服务器的 Minaya

以上各节介绍的是 Minaya 调用你的系统。这里是相反的方向：让你自己的 AI 工具查询你已在此构建的知识库。

连接 Claude、ChatGPT，或你自己编写的代理，它就能搜索你的内容并提出有据可查的问题——享有与网站访客相同的检索能力和防护措施。仅在付费方案中可用。

连接方式

在仪表盘中打开集成，并在Minaya MCP server 下生成一个访问令牌。
立即复制它——它只会显示一次。如果丢失，可生成新的令牌；旧令牌会立刻失效。
将该服务器添加到你的 MCP 客户端：

{
  "mcpServers": {
    "minaya": {
      "type": "http",
      "url": "https://api.minaya.ai/public/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

工具

工具	作用
`search_knowledge_base`	返回与问题最匹配的段落，附带相关性评分和来源 URL。适用于需要原始素材的场景。
`ask`	返回一段严格基于知识库的书面答案。运行经过与挂件相同的防护流程，因此未覆盖的问题会得到你的兜底消息，而非臆测的答案。
`list_sources`	列出已索引的文档和页面，让调用方了解知识库覆盖的内容。

安全性

只读。 没有任何工具会写入、更新或删除内容。令牌泄露也只会暴露你的挂件本就公开提供的内容。
范围限定于单个挂件。 令牌只能访问其生成时所对应的知识库，无法访问你账户中的其他任何内容。
与站点密钥相互独立。 站点密钥是公开的，存在于你的页面 HTML 中。而此令牌是保密的——不要将其放入客户端代码或公开仓库。
降级后会被撤销。 每次调用都会重新根据你的方案检查访问权限。
速率限制为每分钟 60 次调用。