# Cursor

> 让 Cursor 的 Agent 实时访问网络——从 Cursor Directory 一键安装 Search1API 插件，或在 mcp.json 中配置托管的 MCP 服务器。

Canonical URL: https://s1.dev/zh/docs/integrations/cursor

Search1API 已作为插件发布在 [Cursor Directory](https://cursor.directory/plugins/search1api)。安装后，Cursor 会连接到托管的 Search1API MCP 服务器，Agent 在处理代码时就能搜索网页、阅读页面、查看热门内容——无需离开编辑器，也无需自己编写集成。

## Agent 可用的工具

| 工具 | 作用 | 必填参数 |
| --- | --- | --- |
| `search` | 网页搜索 | `query` |
| `news` | 新闻搜索 | `query` |
| `crawl` | 读取 URL | `url` |
| `sitemap` | 列出网站的链接 | `url` |
| `trending` | GitHub / Hacker News 热门 | `search_service` |

## 安装

### 从 Cursor Directory 一键安装

1. 打开 [cursor.directory/plugins/search1api](https://cursor.directory/plugins/search1api)。
2. 选择 **Add to Cursor**。浏览器会把安装交给 Cursor 桌面应用。
3. 检查 Cursor 显示的配置——它应当只包含托管端点：

   ```json
   {
     "url": "https://mcp.search1api.com/mcp"
   }
   ```

4. 确认安装，然后在 Cursor 于浏览器中打开 Search1API 授权页面时登录。

整个过程不涉及 API 密钥：配置项只包含服务器 URL，Cursor 会在首次连接时完成 OAuth。

### 在 `mcp.json` 中手动配置

Cursor 从两个文件读取 MCP 服务器：

| 文件 | 作用范围 |
| --- | --- |
| `~/.cursor/mcp.json` | 所有项目 |
| `.cursor/mcp.json` | 单个项目 |

<Tabs items={['OAuth', 'API 密钥']}>

<Tab value="OAuth">

只需配置端点。Cursor 会通过 Search1API 的 `WWW-Authenticate` 质询发现授权服务器、完成自身注册，并提示你登录：

```json
{
  "mcpServers": {
    "search1api": {
      "url": "https://mcp.search1api.com/mcp"
    }
  }
}
```

</Tab>

<Tab value="API 密钥">

在 [app.s1.dev](https://app.s1.dev) 创建密钥，并以 Bearer Token 发送：

```json
{
  "mcpServers": {
    "search1api": {
      "url": "https://mcp.search1api.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SEARCH1API_KEY"
      }
    }
  }
}
```

对于 `~/.cursor/mcp.json`，这样就够了。项目级的 `.cursor/mcp.json` 通常会提交到版本控制，此时应把密钥换成 `"Bearer ${env:SEARCH1API_KEY}"`，并在 shell 配置文件中导出 `SEARCH1API_KEY`——Cursor 会解析 `url` 和 `headers` 中的 `${env:NAME}`。注意，Cursor 的 `envFile` 字段无法实现这一点：它只适用于 stdio，对远程服务器会被忽略。

</Tab>

</Tabs>

编辑文件后重启 Cursor。

## 验证

1. 在 Cursor 侧边栏打开 **Customize**，确认 Search1API 服务器已列出并已启用。它应显示上面的五个工具。
2. 在对话中输入：`Search the web for the latest Next.js release notes and cite the sources.`
3. Cursor 请求确认时，批准工具调用。

Cursor 会在 `Available Tools` 下列出已连接的工具，并在请求需要最新信息时自行调用，包括在 Plan 模式下。你也可以直接点名某个工具，例如“对这个 URL 使用 crawl 工具”。

## 故障排查

### 服务器没有出现

检查 JSON 是否有效，且位于 `~/.cursor/mcp.json` 或 `<project>/.cursor/mcp.json`，然后重启 Cursor。在 **Customize** 中确认该服务器已开启。

### 查看 MCP 日志

打开 Output 面板（macOS 上为 `Cmd+Shift+U`，Windows 和 Linux 上为 `Ctrl+Shift+U`），并在下拉菜单中选择 **MCP Logs**。这里会显示连接尝试、授权质询和工具错误。

### `401 Unauthorized`

使用 OAuth 时，表示会话已过期或被撤销——移除服务器后重新添加即可重新授权。使用 API 密钥时，表示密钥无效或已被撤销。如果你使用了 `${env:SEARCH1API_KEY}`，还要确认该变量确实传到了 Cursor：从一个 `echo $SEARCH1API_KEY` 能输出密钥的 shell 中启动 Cursor，或者临时直接粘贴密钥来定位问题。参见[认证](https://s1.dev/zh/docs/essentials/authentication)。

### `402 Payment Required`

账户积分已用完。参见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

### 工具已连接但从未被调用

明确描述需求（“在网上搜索……”“读取这个 URL……”）或直接点名工具。是否调用工具由 Cursor 自行判断。

## 计费

来自 Cursor 的工具调用就是普通的 API 调用，与你直接调用端点消耗相同的积分、按相同费率计费。一次搜索或新闻请求消耗 1 积分；抓取页面每页消耗 1 积分。参见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

## 相关文档

- [MCP 服务器](https://s1.dev/zh/docs/integrations/mcp)——完整的端点参考、OAuth 细节及其他客户端
- [Agent Skill](https://s1.dev/zh/docs/integrations/skills)——教 Agent *何时*搜索，而不只是如何搜索
- [搜索 API](https://s1.dev/zh/docs/basic/search) · [抓取 API](https://s1.dev/zh/docs/basic/crawl)
- [Cursor Directory 页面](https://cursor.directory/plugins/search1api) · [Cursor MCP 文档](https://cursor.com/docs/mcp)

源码：[github.com/superagents-lab/search1api-mcp](https://github.com/superagents-lab/search1api-mcp)