> 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/use-tools-get-started/install-assay-mcp.md).

# Install assay-mcp

Install the local Assay MCP server in your AI client and sign in with OAuth.

`assay-mcp` runs on your computer and connects your AI client to Assay over stdio. It forwards tool calls and can sign payments locally after you approve spending permission.

You need Node.js **20 or newer**, your client installed, and a usable OS keychain. Hosted connectors in claude.ai and ChatGPT make free calls only; use a local client below for paid calls.

## Install in your client

These steps install the server as `assay` and connect to `https://mcp.goassay.ai/`, the default Assay URL. You do not put an API key or tokens in the client config.

### Use the add helper

The helper writes the client entry for you, for any of the seven clients. For example, for Claude Code:

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

Replace `claude-code` with the ID for your client:

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

The default scope is your user account. If the helper asks to allow paid calls through the URL, read the prompt and type the profile name it shows (`default` unless you passed `--profile`). This allows the URL locally; wallet approval is still needed before the key can pay.

### Or add the entry by hand

Choose one tab.

{% tabs %}
{% tab title="Claude Code" %}
Run in a terminal:

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

{% endtab %}

{% tab title="Codex CLI" %}
Run in a terminal:

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

{% endtab %}

{% tab title="Gemini CLI" %}
Run in a terminal:

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

{% endtab %}

{% tab title="VS Code" %}
Run in a terminal with POSIX shell quoting, such as bash or zsh:

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

For another shell, use the `add` helper above.
{% endtab %}

{% tab title="Cursor" %}
Merge this entry into `~/.cursor/mcp.json`, keeping any other servers:

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

{% endtab %}

{% tab title="Windsurf" %}
Merge this entry into `~/.config/devin/mcp_config.json`, keeping any other servers:

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

{% endtab %}

{% tab title="Claude Desktop" %}
Merge the JSON below into `claude_desktop_config.json`, keeping any other servers. The file is at:

| OS      | File                                                              |
| ------- | ----------------------------------------------------------------- |
| 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"]
    }
  }
}
```

Use this local stdio entry for paid calls. A remote connector in Claude Desktop is free-only.
{% endtab %}
{% endtabs %}

`list`, `remove` and `status` track only entries written by the `add` helper. An entry you add by hand works, but you manage it in the client. To manage it from the CLI, use the helper instead.

## Sign in

1. Open or restart your client so it loads `assay`.
2. Ask it to call `assay_sign_in`. Before sign-in, this is the only Assay tool offered. It opens your browser and returns a sign-in link; open that link yourself if the browser did not open.
3. Sign in to Assay. On **Connect an app to Assay**, review the requesting app, select the agent it should use, and choose **Approve** to approve the connection.
4. Return to your client. Assay tools appear after approval. Ask it to find a free tool and call it.

Sign-in uses OAuth authorization code flow with PKCE and a local callback. Access and refresh tokens stay in the OS keychain. The default URL `/` becomes allowed for paid calls at sign-in, but sign-in does not create a payment key or approve spending.

## Check it worked

The client can list Assay tools and return a free tool result. If the tool list has not refreshed after approval, restart the client.

## Errors

| Reason                              | Meaning                                                                                        | Fix                                                                                            |
| ----------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| No usable OS keychain               | The server cannot store secrets safely and will not start.                                     | Make an OS keychain available before starting the client.                                      |
| Keychain locked                     | The server cannot read its stored secrets.                                                     | Unlock your keychain and try again.                                                            |
| Sign-in ended on the web or expired | Calls return a sign-in link and a terminal command; the browser does not reopen automatically. | Open the returned link, or run `npx -y @goassay-ai/mcp login` in a terminal and approve again. |

## Go further

* Use tools (optional): [Connect your AI app](https://docs.goassay.ai/use-tools/connect-your-ai-app)

## Next

* [How paying works](/developers/use-tools-get-started/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/use-tools-get-started/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.