mistral.rs 将模型暴露为 MCP 服务器--mcp-port配置、JSON-RPC 方法与 chat 工具实战指南【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rsmistral.rs 内置了 MCPModel Context Protocol服务器能力一条mistralrs serve --mcp-port命令即可把已加载的 LLM 变成一个标准 MCP 工具服务器任何遵循 MCP 协议的客户端Claude Desktop、Cursor、自研 Agent 等都能通过 JSON-RPC 2.0 调用它把本地模型接入到外部 Agent 生态中。本文将以 docs/src/content/docs/guides/agents/expose-as-mcp.md 为主线结合 CLI 参数解析、服务启动与 MCP 路由实现 的源码细节完整讲解端口配置规则、四个 MCP 方法的行为、chat工具的请求/响应格式以及安全注意事项帮助你快速搭建一个可被任意 MCP 客户端发现的推理服务。一、快速开始一条命令启动 MCP 服务器在已经安装好 mistral.rs CLI 的环境中启动一个同时提供 OpenAI 兼容 API 与 MCP 端点服务的最简命令如下mistralrs serve -m Qwen/Qwen3-4B --mcp-port 4321执行后你会得到两个并存的 HTTP 监听器主 APIOpenAI 兼容接口继续运行在--port默认1234新增的 MCP 端点运行在--mcp-port此处为4321监听路径为POST /mcp。启动日志会明确打印两条地址例如Server listening on http://0.0.0.0:1234 MCP server listening on http://0.0.0.0:4321/mcp MCP protocol version is 2025-11-25二、--mcp-port端口规则与启动校验根据 mistralrs-cli/src/args/server.rs 的定义mcp_port是一个可选的u16端口号/// Also expose the loaded model as an MCP server on this port (JSON-RPC 2.0 at POST /mcp). #[arg(long)] #[serde(default)] pub mcp_port: Optionu16,围绕该参数有四条必须遵守的规则共享--host绑定地址MCP 监听器与主 HTTP API 使用同一个host默认0.0.0.0这意味着两者的网络暴露范围一致OpenAI 兼容 API 照常运行--mcp-port只是追加一个监听器原有的--port服务含/v1/chat/completions等路由不受影响可以同时被 HTTP 客户端与 MCP 客户端使用--mcp-port必须与--port不同在 serve.rs 的 spawn_mcp_server 中启动时会先做相等性校验if mcp_port http_port { anyhow::bail!(--mcp-port must differ from the HTTP --port ({http_port})); }绑定在启动阶段即被验证spawn_mcp_server会立即执行TcpListener::bind(format!({host}:{mcp_port}))一旦端口被占用或绑定失败错误会在服务真正对外提供请求之前浮出水面Failed to bind MCP server to {host}:{mcp_port}不会出现服务起来了但 MCP 不可用的隐蔽故障。绑定成功后axum::serve在独立 tokio 任务中运行 MCP 路由与主 API 互不阻塞。TOML 配置方式不使用命令行时可以在 TOML 配置文件的[server]段中声明mcp_port等价于--mcp-port字段与 CLI flag 的映射见 cli-toml-config.mdcommand serve [server] port 1234 mcp_port 4321[server]段同时支持host默认0.0.0.0等字段mcp_port缺省时NoneMCP 端点不会启动。三、MCP 协议与端点语义客户端访问的地址为http://host:mcp_port/mcp每次调用都是携带 JSON-RPC 2.0 请求体的POST /mcp。在源码层面路由由 create_mcp_router 构建请求体被反序列化为JsonRpcRequest { jsonrpc, id, method, params }响应统一为JsonRpcResponse { jsonrpc, id, result, error }信封结构。支持的四个方法方法行为响应示例result 部分initialize握手返回协议版本、能力声明与服务器信息{capabilities:{tools:{}},instructions:...,protocolVersion:2025-11-25,serverInfo:{name:mistralrs,version:...}}ping健康检查{}tools/list列出可用工具模型不具备文本输入/输出模态时返回空列表{tools:[{name:chat,...}]}或{tools:[]}tools/call执行chat工具走模型推理路径{content:[{type:text,text:...}]}initialize中的instructions字段是固定的提示文本告知调用方该服务器提供 LLM 文本与多模态推理可使用chat工具发送带消息历史的聊天补全请求便于 Agent 理解工具用途serverInfo.version来自编译期常量env!(CARGO_PKG_VERSION)即当前构建的 crate 版本与协议版本2025-11-25一起构成握手信息protocolVersion常量定义在 mcp_server.rs 顶部MCP_ROUTE /mcp、MCP_PROTOCOL_VERSION 2025-11-25。错误码约定除上述四个方法外的任何方法名都会得到 JSON-RPC 错误-32601method not found请求体中的jsonrpc字段不是2.0时返回-32600invalid request工具执行失败返回-32603internal error。源码中的常量与之一一对应const PARSE_ERROR: i32 -32700; const INVALID_REQUEST: i32 -32600; const INVALID_PARAMS: i32 -32602; const METHOD_NOT_FOUND: i32 -32601; const INTERNAL_ERROR: i32 -32603;另外请求体本身无法解析为合法 JSON 时返回-32700parse errortools/call中参数校验失败如缺少messages、字段类型错误返回-32602invalid params。单测 mcp_server.rs 的 tests 模块 覆盖了握手结果、工具列表、未知方法与错误信封格式等行为可作为协议实现的权威参考。四、chat工具把任意 ChatCompletion 参数透传给模型tools/list返回的工具名为chat其 JSON Schema 只声明了最常用的字段但实际执行时可以传入任意 OpenAIChatCompletionRequest字段——arguments会被整体反序列化为ChatCompletionRequest后再走与 HTTP API 相同的请求解析与推理管线见 call_chat_tool。Schema 要点必填messages{role, content}对象数组role限定为user、assistant、system三者之一文档化max_tokens生成的最大 token 数与temperature采样温度Schema 声明范围0.0 ~ 2.0默认值model缺省为default即使用服务启动时加载的唯一模型。一个完整的tools/call请求示例curl http://localhost:4321/mcp \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: chat, arguments: { messages: [{role: user, content: Hello!}], max_tokens: 50 } } }返回结果是标准的 MCP 工具调用内容块{content: [{type: text, text: Hello! How can I help?}]}工具可用性与推理细节tools/list的返回并非固定不变create_mcp_router会根据模型配置的SupportedModality动态决定是否暴露chat工具——只有当模型同时具备文本输入与文本输出模态时才返回chat工具否则列表为空例如纯视觉或多模态输出模型。这一点在测试tools_list_exposes_chat_for_text_models与tools_list_is_empty_without_text_modality中均有断言。推理执行时响应通道会过滤掉 Agentic 工具调用进度、去噪进度与文件类中间消息仅在Done时把所有 choice 的文本内容拼接以换行分隔作为工具结果返回参数错误则映射为-32602内部错误映射为-32603。五、身份认证与暴露边界MCP 端点没有内置身份认证。mistralrs serve默认host 0.0.0.0即绑定所有网卡接口MCP 端点与主 API 一样会直接暴露在网络上。因此在非 localhost 场景下部署时必须在前面放置一个承担认证/授权的反向代理如 nginx、oauth2-proxy 等切勿裸奔。仅本机使用时将host设为127.0.0.1即可把访问限制在本地。与[server]段的mcp_port不同MCP客户端配置mcp_config位于[runtime]段适用于run与serve两种模式——那是mistral.rs 作为 MCP 客户端去连接外部工具服务器的反向场景参见 connect-mcp-server 与 mcp_client.py 示例。六、与 HTTP API 及工具调用的关系与 OpenAI 兼容 API 并存/v1/chat/completions等路由不受影响MCP 只是同一模型状态SharedMistralRsState之上的另一条入口与 agentic 能力的衔接chat工具走的是与 HTTP 一致的 ChatCompletion 解析管线因此max_tool_rounds、tool_dispatch_url等 serve 参数 所开启的服务器端工具执行能力同样作用于 MCP 调用反向场景如果你想反过来让 mistral.rs 调用外部 MCP 工具文件系统、搜索等请参考 connect-mcp-server两个方向配合使用即可构建模型既是 MCP 服务端、又是 MCP 客户端的完整 Agent 网络。参考Serve over MCP 官方指南本文主题文档MCP 服务器实现源码serve 命令中 MCP 监听器启动逻辑CLI 服务参数定义含--mcp-portTOML 配置参考[server]段Connect to an MCP server反向用法【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
