# MCP 服务器

> 通过托管的 Search1API MCP 端点，让 Claude、Cursor、VS Code 或任意 MCP 客户端获得实时网络访问能力，无需编写代码。

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

Search1API 提供一个托管的 MCP 服务器，地址为：

```
https://mcp.search1api.com/mcp
```

将支持 OAuth 的 MCP 客户端指向该地址，Search1API 会自动声明授权流程。不支持 OAuth 发现的客户端可以继续使用 API 密钥。无论哪种方式，模型都可以搜索网页、读取页面并查看热门内容，你无需自己编写集成。

## 提供的工具

| 工具 | 作用 | 必填 |
| --- | --- | --- |
| `search` | 网页搜索 | `query` |
| `news` | 新闻搜索 | `query` |
| `ask` | 描述你的需求，由 Search1API 选择引擎和时间范围 | `query` |
| `crawl` | 读取 URL | `url` |
| `sitemap` | 列出站点的链接 | `url` |
| `trending` | GitHub / Hacker News 热门 | `search_service` |
| `render_results` | 将已选定的现有来源以卡片或易读列表的形式展示；不消耗搜索积分 | `results` |

## 展示选定的来源

远程端点以及通过 stdio 运行的 `search1api-mcp` 0.8.0+ 在数据工具之外还提供 `render_results`。连接 URL 保持不变：

```text
https://mcp.search1api.com/mcp
```

`search`、`news` 和 `ask` 获取结果时不会自动展示卡片。当来源列表对任务有帮助时，模型可以挑选、组合现有结果，并将其传给 `render_results`：

```json
{
  "title": "Selected sources",
  "results": [
    {
      "id": "https://s1.dev/docs",
      "title": "Search1API documentation",
      "url": "https://s1.dev/docs"
    }
  ]
}
```

`results` 为必填，可包含 0–50 个条目。每个条目必须包含 `title` 和一个 HTTP(S) `url`；`id`、`text` 中的来源摘要（最多 2,000 个字符）以及原始 `metadata` 为可选。列表的 `title` 为可选，默认值为 `Results`。请保留来源的原始标题和链接。绘制卡片不需要完整的已抓取页面。

该工具返回包含 `title`、`total` 和 `results` 的 `structuredContent`，并在 `content` 中附带一份完整的易读来源列表。MCP Apps 客户端可以展示卡片；不支持 UI 或结构化输出的客户端仍会以文本形式收到标题、链接和摘要。空列表也会成功返回，内容为 “No results to display.”

渲染和展开卡片不会执行搜索、获取页面，也不会消耗搜索积分。工具调用成功只表示结果已准备好，不代表宿主已经展示了它们。普通的带引用回答和中间调研步骤不需要调用渲染工具。

无需配置 UI URL 参数。保留现有的 OAuth 或 API 密钥认证即可；如果看不到 `render_results`，请重新连接或刷新工具发现。两种传输方式返回相同的结构化 JSON 和文本列表，由客户端决定是否加载 UI。来源卡片的展示已在 ChatGPT 桌面端以及 Claude 网页端、桌面端和移动端验证。UI 是否可用取决于宿主及其版本。通过目录添加的连接可能需要宿主审核后，新增的工具才会出现。对于本地 stdio，请升级到 0.8.0+ 并重启 MCP 连接。

## 连接你的客户端

### Claude 目录（Claude 用户推荐）

Search1API 同时以连接器和插件的形式发布。两者都使用这个托管 MCP 服务器和相同的托管工具；插件额外包含一个 Agent Skill。两者的对比和安装步骤见 [Claude 指南](https://s1.dev/zh/docs/integrations/claude)。

- **[添加 Search1API 连接器](https://claude.ai/directory/search1api)：** 将其添加到 Claude，然后通过 OAuth 使用你的 Search1API 账户登录。这样即可在 Claude 网页端、桌面端和移动端使用托管的 MCP 工具。
- **[安装 Search1API 插件](https://claude.ai/customize/plugins/id/c73feffb-aae4-49f4-8515-24322b313989%40anthropic-plugin-directory)：** 添加插件，然后连接 Search1API。插件将相同的 MCP 工具与一个 Agent Skill 打包在一起，支持 Claude 应用、Cowork 和 Claude Code。插件需要付费的 Claude 套餐。

添加到 Claude 账户的插件，会同步到使用同一账户登录的 Claude Code v2.1.273 或更高版本。如果想在 Claude Code 中直接连接 MCP：

```bash
claude mcp add --transport http search1api https://mcp.search1api.com/mcp
```

在 Claude Code 中运行 `/mcp`，按提示登录。如果你更想使用 API 密钥，请参考下文的 API 密钥备用方案。

### OAuth 2.1（首选）

对于支持 OAuth 发现的客户端，只需配置端点：

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

外层配置键因客户端而异，但服务器 URL 相同。首次连接时，服务器会返回一个 `WWW-Authenticate` 质询，指向：

```
https://mcp.search1api.com/.well-known/oauth-protected-resource/mcp
```

随后客户端可以发现 Search1API 的授权服务器，进行动态注册，并使用 Authorization Code + PKCE 流程。账户所有者在浏览器中登录并批准访问。请求了 `offline_access` 的客户端可以为长时间运行的会话刷新访问令牌。

> **info:** 是否支持 OAuth 取决于 MCP 客户端。如果客户端不遵循受保护资源发现流程，请使用下文的 API 密钥配置。

### API 密钥备用方案

在 [app.s1.dev](https://app.s1.dev) 创建密钥，然后使用对应客户端的配置。仪表盘的 **MCP** 页面可以生成已填入密钥的示例配置。

<Tabs items={['Claude Code', 'Cursor', 'VS Code', 'Windsurf']}>

<Tab value="Claude Code">

```bash
claude mcp add --transport http search1api https://mcp.search1api.com/mcp \
  --header "Authorization: Bearer YOUR_SEARCH1API_KEY"
```

</Tab>

<Tab value="Cursor">

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

Cursor 还支持一键安装，并有自己的 `mcp.json` 约定，详见 [Cursor](https://s1.dev/zh/docs/integrations/cursor)。

</Tab>

<Tab value="VS Code">

注意键名不同（是 `servers`，不是 `mcpServers`），并且必须填写 `type`：

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

</Tab>

<Tab value="Windsurf">

Windsurf 通过 URL 而不是请求头传递密钥：

```json
{
  "mcpServers": {
    "search1api": {
      "serverUrl": "https://mcp.search1api.com/mcp?apiKey=YOUR_SEARCH1API_KEY"
    }
  }
}
```

</Tab>

</Tabs>

### 通过 Smithery 安装（可选）

想要一键安装？Search1API 已上架 [Smithery](https://smithery.ai/servers/superagents-lab/search1api-mcp)，它支持 20 多种 MCP 客户端（Claude Code、Codex、Cursor、Windsurf、Gemini CLI 等）。对于支持技能的宿主，还提供 [search1api agent skill](https://smithery.ai/skills/superagents-lab/search1api)。

## 认证方式

托管服务器接受在 `Authorization: Bearer <credential>` 请求头中传入 OAuth 访问令牌或 Search1API API 密钥。OAuth 令牌和 API 密钥使用同一 Search1API 账户的积分、计费和速率限制。

未提供凭证时，服务器返回 `401` 质询，并附带其受保护资源元数据 URL。无效或过期的 OAuth 令牌会返回相同的质询，并带有 `error="invalid_token"`，以便兼容的客户端刷新令牌或重新授权。

对于无法发送请求头的旧版客户端，服务器也接受通过 `?apiKey=<key>` 查询参数传入 API 密钥。两者同时存在时，以请求头为准。

使用查询参数认证意味着密钥会出现在 URL 中，可能被记录到日志和 shell 历史里。只要客户端支持，请优先使用 OAuth 或 Bearer 请求头。

## 协议支持

托管服务器实现了 Model Context Protocol 的 `2026-07-28` 修订版，该版本于 2026 年 7 月 28 日发布。此修订版移除了协议层面的会话和 `initialize` 握手：每个请求都在 `_meta` 中携带自己的协议版本和客户端能力，服务器则在每个结果中标明自身身份。

使用 `2026-07-28` 的请求，除普通的 JSON-RPC 请求体外，还需要两项内容：

- 一个与请求体中 `method` 一致的 `Mcp-Method` 请求头；
- 一个 `_meta` 对象，包含 `io.modelcontextprotocol/protocolVersion`、`io.modelcontextprotocol/clientInfo` 和 `io.modelcontextprotocol/clientCapabilities`。

在发送其他请求之前，先调用 `server/discover` 读取支持的版本、能力和服务器身份：

```bash
curl -sS -X POST https://mcp.search1api.com/mcp \
  -H "Authorization: Bearer YOUR_SEARCH1API_KEY" \
  -H "Mcp-Method: server/discover" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
```

它会返回支持的修订版和服务器身份：

```json
{
  "result": {
    "supportedVersions": ["2026-07-28"],
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "listChanged": true }
    },
    "resultType": "complete",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "search1api-server",
        "version": "0.5.1"
      }
    }
  }
}
```

将 `Mcp-Method` 请求头和 `method` 字段换成 `tools/list`，同样的请求结构就会返回上面列出的工具。

> **info:** 使用 2025 协议修订版的客户端无需任何改动即可继续工作。以 `2025-06-18` 发送 `initialize` 的客户端，在 HTTP 和 stdio 上仍会收到正常响应，因此你现有的配置都无需调整。

## 改为在本地运行

该服务器也可以通过 stdio 直接从 npm 运行：

```json
{
  "mcpServers": {
    "search1api": {
      "command": "npx",
      "args": ["-y", "search1api-mcp@latest"],
      "env": {
        "SEARCH1API_KEY": "YOUR_SEARCH1API_KEY"
      }
    }
  }
}
```

0.8.0 版本包含全部七个工具以及内置的 MCP Apps 视图。要升级全局安装，请运行 `npm install -g search1api-mcp@latest`；对于 `npx` 配置，请按上例使用 `search1api-mcp@latest` 并重启客户端。

本地 stdio 包使用 API 密钥。MCP 协议本身不会经过我们的网络，但其 API 调用仍会发送到 `api.search1api.com`。

## 服务器图标

两种传输方式都通过标准的 `serverInfo.icons` 声明方形的 Search1API 标志，是否展示由客户端决定。该图标是一个公开的 512×512 PNG，由 MCP 源站提供，无需认证。

## 计费

MCP 工具调用就是普通的 API 调用：它们按与直接调用端点相同的费率消耗相同的积分。详见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

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