> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md).

# 安装 assay-mcp

在 AI 客户端中安装本地 Assay MCP 服务器，并通过 OAuth 登录。

`assay-mcp` 在你的电脑上运行，通过 stdio 将 AI 客户端连接到 Assay。它会转发工具调用，并在你批准支出权限后，在本地为付款签名。

你需要 Node.js **20 或更新版本**、已安装的客户端，以及可用的操作系统密钥链。claude.ai 和 ChatGPT 中的托管连接器只能进行免费调用；付费调用请使用下列本地客户端。

## 在客户端中安装

以下步骤将服务器安装为 `assay`，并连接到 Assay 的默认 URL `https://mcp.goassay.ai/`。无需在客户端配置中填写 API 密钥或令牌。

### 使用 add 辅助命令

辅助命令会为你写入客户端条目，支持全部七个客户端。例如，Claude Code：

```sh
npx -y @goassay-ai/mcp add / --client claude-code
```

将 `claude-code` 替换为你的客户端 ID：

| 客户端            | ID               |
| -------------- | ---------------- |
| Claude Code    | `claude-code`    |
| Codex CLI      | `codex`          |
| Gemini CLI     | `gemini`         |
| VS Code        | `vscode`         |
| Cursor         | `cursor`         |
| Windsurf       | `windsurf`       |
| Claude Desktop | `claude-desktop` |

默认安装范围是你的用户账户。如果辅助命令询问是否允许通过此 URL 进行付费调用，请阅读提示，并输入提示中显示的配置文件名称（未传入 `--profile` 时为 `default`）。这只会在本地允许该 URL；密钥付款前仍需钱包批准。

### 或者手动添加条目

选择一个选项卡。

{% tabs %}
{% tab title="Claude Code" %}
在终端中运行：

```sh
claude mcp add --scope user assay -- npx -y @goassay-ai/mcp --name assay
```

{% endtab %}

{% tab title="Codex CLI" %}
在终端中运行：

```sh
codex mcp add assay -- npx -y @goassay-ai/mcp --name assay
```

{% endtab %}

{% tab title="Gemini CLI" %}
在终端中运行：

```sh
gemini mcp add --scope user assay npx -y @goassay-ai/mcp --name assay
```

{% endtab %}

{% tab title="VS Code" %}
在使用 POSIX shell 引号规则的终端（如 bash 或 zsh）中运行：

```sh
code --add-mcp '{"name":"assay","type":"stdio","command":"npx","args":["-y","@goassay-ai/mcp","--name","assay"]}'
```

如果使用其他 shell，请用上方的 `add` 辅助命令。
{% endtab %}

{% tab title="Cursor" %}
将此条目合并到 `~/.cursor/mcp.json`，保留其他服务器：

```json
{
  "mcpServers": {
    "assay": {
      "command": "npx",
      "args": ["-y", "@goassay-ai/mcp", "--name", "assay"]
    }
  }
}
```

{% endtab %}

{% tab title="Windsurf" %}
将此条目合并到 `~/.config/devin/mcp_config.json`，保留其他服务器：

```json
{
  "mcpServers": {
    "assay": {
      "command": "npx",
      "args": ["-y", "@goassay-ai/mcp", "--name", "assay"]
    }
  }
}
```

{% endtab %}

{% tab title="Claude Desktop" %}
将下方 JSON 合并到 `claude_desktop_config.json`，保留其他服务器。文件位置如下：

| 操作系统    | 文件                                                                |
| ------- | ----------------------------------------------------------------- |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json` |
| Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

```json
{
  "mcpServers": {
    "assay": {
      "command": "npx",
      "args": ["-y", "@goassay-ai/mcp", "--name", "assay"]
    }
  }
}
```

付费调用请使用这个本地 stdio 条目。Claude Desktop 中的远程连接器只能进行免费调用。
{% endtab %}
{% endtabs %}

`list`、`remove` 和 `status` 只跟踪由 `add` 辅助命令写入的条目。手动添加的条目可以正常使用，但需要你在客户端中管理。如果想通过 CLI 管理，请改用辅助命令。

## 登录

1. 打开或重启客户端，让它加载 `assay`。
2. 请客户端调用 `assay_sign_in`。登录前，这是唯一可用的 Assay 工具。它会打开浏览器并返回登录链接；如果浏览器未打开，请自行打开该链接。
3. 登录 Assay。在 **Connect an app to Assay** 页面，检查发起请求的应用，选择它应使用的智能体，然后选择 **Approve** 批准连接。
4. 返回客户端。批准后会出现 Assay 工具。请客户端查找一个免费工具并调用。

登录采用带 PKCE 的 OAuth 授权码流程和本地回调。访问令牌和刷新令牌保存在操作系统密钥链中。登录时，默认 URL `/` 会获得付费调用许可，但登录不会创建支付密钥，也不会批准支出。

## 确认是否成功

客户端能够列出 Assay 工具并返回免费工具的结果。如果批准后工具列表未刷新，请重启客户端。

## 错误

| 原因             | 含义                          | 解决方法                                                 |
| -------------- | --------------------------- | ---------------------------------------------------- |
| 没有可用的操作系统密钥链   | 服务器无法安全保存机密信息，因此不会启动。       | 启动客户端前，先确保操作系统密钥链可用。                                 |
| 密钥链已锁定         | 服务器无法读取已保存的机密信息。            | 解锁密钥链后重试。                                            |
| 在网页端结束登录或登录已过期 | 调用会返回登录链接和终端命令；浏览器不会自动重新打开。 | 打开返回的链接，或在终端运行 `npx -y @goassay-ai/mcp login` 并重新批准。 |

## 延伸阅读

* 使用工具（可选）：[连接你的 AI 应用](https://docs.goassay.ai/use-tools/zh/connect-your-ai-app)

## 下一步

* [付费流程](/developers/zh/shi-yong-gong-ju-ru-men/how-paying-works.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.