客户端接入

蜀农 API 的 MCP 端点兼容支持 Streamable HTTP 传输的标准 MCP 客户端。本节给出常见客户端的配置方式，配置完成后模型即可自主调用天气、知识库、图像识别与时间工具。

开始前请先准备好 API Key，参见 获取 API Key 与 鉴权。

通用配置要素

无论使用哪个客户端，需要填写的都是这三项：

不要在浏览器的网页前端里配置这个密钥。API Key 具备账户额度权限，浏览器端配置会把它暴露给任何打开页面的人。客户端配置应写在本地配置文件或服务端环境变量中。

Claude Code

用命令行添加，一条命令完成：

claude mcp add --transport http shunong \
  https://ai.agriwis.com/mcp \
  --header "Authorization: Bearer sk_xxxxxxxxxxxxxxxx"

添加后确认连接状态：

claude mcp list

在会话中查看已加载的工具：

/mcp

需要跨项目共享时加 --scope user，仅当前项目使用则用默认的 --scope local。

Claude Desktop

在配置文件中添加服务。配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shunong": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ai.agriwis.com/mcp",
        "--header",
        "Authorization: Bearer ${SHUNONG_API_KEY}"
      ],
      "env": {
        "SHUNONG_API_KEY": "sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存后完全退出并重启 Claude Desktop，工具图标出现在输入框附近即表示加载成功。

较新版本的 Claude Desktop 支持在「设置 → 连接器」中直接添加远程 MCP，填入服务地址与 Authorization 请求头即可，无需借助 mcp-remote。如果你的版本有该入口，优先使用它，配置更简单。

Cursor

在项目根目录创建 .cursor/mcp.json（仅该项目生效），或编辑全局配置 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "shunong": {
      "url": "https://ai.agriwis.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

修改后在 Cursor 设置的 MCP 面板中确认服务状态为绿色，再在对话中使用 Agent 模式，工具才会被自动调用。

Cline（VS Code 扩展）

点击扩展侧边栏的 MCP Servers 图标 → Configure MCP Servers，在打开的配置文件中添加：

{
  "mcpServers": {
    "shunong": {
      "type": "streamableHttp",
      "url": "https://ai.agriwis.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_xxxxxxxxxxxxxxxx"
      },
      "disabled": false,
      "autoApprove": ["weather_search", "get_current_time", "knowledge_search"]
    }
  }
}

autoApprove 中列出的工具会被自动执行，不再逐个确认。建议只把只读查询类工具放进去，图像识别涉及外部图片下载，保留人工确认更稳妥。

Cherry Studio

设置 → MCP 服务器 → 添加，类型选择「可流式传输的 HTTP（Streamable HTTP）」，依次填入：

• URL：https://ai.agriwis.com/mcp
• 请求头：键填 Authorization，值填 Bearer sk_xxxxxxxxxxxxxxxx

保存后启用开关，服务状态变为已连接即可在对话中调用。

其他客户端

配置项名称因客户端而异，但本质都是「URL + Authorization 请求头」。如果你的客户端配置界面里有以下任一表述，按对应方式填写：

验证与调试

配置不生效时，先用 curl 排除客户端因素，确认端点本身可用：

# 1. 初始化，取出响应头里的 mcp-session-id
curl -s -D headers.txt -X POST https://ai.agriwis.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"debug","version":"1.0.0"}}}'

SID=$(grep -i '^mcp-session-id:' headers.txt | tr -d '\r' | awk '{print $2}')
echo "session: $SID"

# 2. 完成握手（返回 202）
curl -s -o /dev/null -w "initialized: %{http_code}\n" \
  -X POST https://ai.agriwis.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. 拉工具清单
curl -s -X POST https://ai.agriwis.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 4. 调用工具
curl -s -X POST https://ai.agriwis.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $SHUNONG_API_KEY" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"weather_search","arguments":{"location":"成都","date":"now"}}}'

若第 3 步能返回 4 个工具，说明端点和密钥都正常，问题在客户端配置；此时重点检查请求头是否真的带上、客户端是否以 Agent 模式运行。

常见问题排查

安全建议

• 为每个环境（开发、测试、生产）分别创建 API Key，便于按环境撤销和统计用量。
• 定期检查控制台的用量记录，发现异常增长立即撤销对应密钥。
• 客户端侧对工具参数做二次校验。模型生成的参数不可信，尤其是 imageUrl 这类会触发服务端外部请求的字段。
• 日志中不要输出完整 API Key，如需记录请只保留前 6 位与后 4 位。
• 面向最终用户的产品，建议由你的后端代理 MCP 请求，在代理层做用户鉴权、限流与额度控制。