MCP 集成

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

什么是 MCP

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

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

调用是如何进行的

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

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

连接服务器

前往集成并添加：

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

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

限制

限制项	数值	原因
每个企业的服务器数量	5	每条消息都会产生发现延迟成本。
每个会话的工具调用次数	10	限制成本并防止失控循环。
每条消息的轮次	3	模型可以再次获取更多工具，但不能无限进行。
连接超时	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 次调用。