USER GUIDE · v1.0

使用指导

MIXER 开发者平台把"任意代码仓库 → 可被 AI Agent 调用的 MCP Server"压缩到四步。 本指南按使用顺序展开,你可以从头到尾读,也可以直接跳到关心的章节。

一、快速开始 4 步

  1. 注册并登录

    访问首页,点击「立即开始」创建一个账号。系统会自动登录并跳到控制台。

    账号体系基于 Session Cookie(agentbridge_session),7 天内免重新登录;支持密码修改与注销。

  2. 输入代码

    两种方式择一:粘贴单文件代码,或上传 .zip 压缩包(多文件项目推荐)。

    平台会用 LLM 自动识别语言、抽取可被 Agent 调用的函数,生成 MCP 工具定义(含 name / description / inputSchema)。

  3. 配置并生成

    填写:

    • 服务器名称:作为你项目的唯一标识(平台会在其后追加 token 防猜测)
    • 用户 API 地址:你实际业务的 HTTP 接口(可选,本地 stdio 模式不需要)
    • 鉴权方式:无 / API Key(X-API-Key 头)
    • 传输模式:stdio(本地 Claude Desktop)或 streamable-http(平台托管,任意外部客户端可连)

    点击「生成 MCP Server」后,平台会返回完整的可运行文件(可下载 zip,或直接由平台托管)。

  4. 启动 & 接入客户端

    选 streamable-http:点「启动」按钮,平台会在进程内拉起 MCP Server,给你两个 URL——

    • https://<your-host>/mcp/<server_id> —— Streamable HTTP,推荐(Cherry Studio / Cursor / 通用客户端)
    • https://<your-host>/sse/<server_id> —— SSE(Claude Desktop 兼容模式)

    选 stdio:下载 zip 后在本地 python my_server.py 启动,把命令填进 Claude Desktop 配置即可。

    详细的客户端配置步骤见 客户端接入指南。

二、关键概念

工具 (Tool)

一个工具 = 一个可被 Agent 调用的函数抽象,包含三个字段:

{
  "name": "search_products",
  "description": "在商品库里按关键词搜索商品",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query":  { "type": "string", "description": "搜索关键词" },
      "limit":  { "type": "integer", "default": 10 }
    },
    "required": ["query"]
  }
}

所有工具定义组成一份 tools.json,平台用 LLM 帮你从代码里生成,也可以在第二步手动编辑 JSON。

MCP Server

一个 MCP Server 暴露一组工具,对外提供标准 MCP 协议(JSON-RPC)接口。平台生成的 Server 充当代理层:收到 Agent 的工具调用请求,转成对你业务 API 的 HTTP 调用,再把结果按 MCP 协议返回。

代理的好处:你的业务代码不需要任何 MCP 改造,只需暴露普通 HTTP API。平台负责协议翻译、鉴权、参数校验。

鉴权方式

模式说明何时用
none不附加任何凭据内部测试、公开 API
api_key请求加 X-API-Key 头你的 API 已用 Key 鉴权
oauth占位,后续版本支持—

传输模式

模式运行位置客户端
stdio本地进程Claude Desktop
streamable-http平台进程Cherry Studio / Cursor / 任何支持 MCP 的 Web 客户端

streamable-http 又暴露两种 URL:Streamable HTTP(首选)和 SSE 兼容回退,详见 客户端接入。

多租户隔离

每个 MCP Server 的 server_id 格式为 {user_id}_{safe_name}_{token}:

请把 URL 当作密码对待。任何拿到 server_id 的人都能调用你的工具、消耗你的 API 配额。不同账号之间的 Server 互不可见。

账号与权限

三、常见问题

Q: 启动时提示 "Failed to load MCP server"?

通常是生成的文件语法有误,或 LLM 抽出的工具定义不合法。回到第 2 步用「编辑 JSON」手改 tools.json,确保每个 tool 的 inputSchema 是有效 JSON Schema。

Q: 客户端连得上但工具列表为空?

检查 Server 的 tools 数组。零工具的 Server 不会暴露任何方法。回到控制台点「查看提取的工具」确认。

Q: 怎么停掉一个运行中的 Server?

控制台第 3 步的状态卡片有「停止」按钮,或调用 DELETE /api/v1/run/{server_id}。Server 停止后,任何客户端再连会得到 404。

Q: 注销账号会把 Server 一起删掉吗?

会。DELETE /api/v1/auth/me 会在删除用户行之前先停掉该用户所有运行中的 Server,确保 /mcp/{id} URL 不会留下"孤儿"。

Q: 部署到生产要注意什么?