纳米AI调用MCP工具失败，核心原因通常是客户端与服务器之间的握手流程未完成。解决时需要先确认当前版本不低于 v0.9.3，并确保已开启 MCP 开关；随后正确配置 mcp.json 指向本地运行的 filesystem 服务器，例如 http://localhost:12305/mcp。完成后重启程序，并检查状态栏是否显示 “MCP: connected”，以及工具调用是否能够正常返回响应。
如果你想让纳米AI（Nano AI）通过 MCP 协议调用本地浏览器、读取本地文件或访问数据库，却一直卡在配置步骤，比如修改配置后不生效、工具列表为空，或调用时提示 “server not found”，那大概率并不是模型本身出错，而是 MCP 客户端与服务器之间没有成功完成握手连接。
确认纳米AI是否原生支持MCP
首先进入纳米AI设置页面，在「高级功能」或「实验性选项」中查找“启用外部工具协议（MCP）”开关并手动开启。如果这里根本找不到该选项，基本可以判断当前客户端版本低于 v0.9.3。因为自 2026 年 6 月发布的正式版开始，纳米AI才正式内置 MCP Client 支持。遇到这种情况，需要前往 nanoai.dev/releases 下载最新版安装包并直接覆盖升级。尤其要注意，旧版本即使强行添加 MCP 配置，也通常会静默失败，不仅无法生效，而且不会给出明确报错信息。
验证方式：启动纳米AI后，在命令行执行 nanoai --version，输出结果中必须包含 mcp: enabled 字样。
配置MCP服务器：两种路径任选其一
方法一：使用npm托管的轻量级服务器（推荐新手）
以文件读写场景为例，可直接执行：npx -y @modelcontextprotocol/server-filesystem@latest --port 12305
当终端显示 Server listening on http://localhost:12305/mcp 时，就表示 MCP 文件系统服务器已经成功启动。该命令会自动下载并运行所需组件，无需额外进行全局安装。
方法二：手动部署Python版服务器（适合企业环境）
克隆官方仓库：git clone https://github.com/modelcontextprotocol/servers.git && cd servers/python/filesystem
安装依赖：uv pip install -e .
启动服务：python -m mcp_servers.filesystem --port 12305
【注意】必须使用 uv 而不是 pip install，否则依赖解析可能遗漏 pydantic-core 的特定版本，最终导致 tools/list 返回空数组。
在纳米AI中注册MCP服务器
第一步：定位配置文件
纳米AI采用全局单一配置文件，默认路径为：
Linux/macOS：~/.config/nanoai/mcp.json
Windows：%APPDATA%nanoaimcp.json
如果该文件不存在，请手动新建。
第二步：写入服务器定义
使用文本编辑器打开 mcp.json，填入以下内容（只保留一个 server 条目，不要嵌套数组）：{"filesystem":{"url":"http://localhost:12305/mcp"}}
保存后关闭编辑器。
第三步：重启纳米AI并触发初始化
先彻底退出纳米AI进程（可在任务管理器中确认 nanoai.exe 或 nanoai 进程已完全消失）→ 再重新启动程序 → 在聊天框输入任意一句话（例如“你好”）→ 观察底部状态栏是否出现 “MCP: connected” 提示。若没有出现，说明配置尚未被正确加载，常见原因包括 JSON 格式错误（如多余逗号、缺少引号）或端口已被占用。
验证工具是否就绪并发起首次调用
在纳米AI聊天窗口输入：
“请读取我桌面的 README.md 文件内容”
如果返回结构化错误（例如 {"error":"tool_not_found","tool":"filesystem.read_file"}），说明 MCP 服务器没有正确暴露工具列表，需要检查服务器日志中是否打印了 tools/list requested；如果返回超时、连接失败或连接被拒绝，则通常是 URL 地址填写错误，或者服务器实际上并未运行。
成功响应示例：
“已读取文件，共127行，前三行为：# Nano AI MCP Demo\n\nThis configures local file access…”