> 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-advanced/cli-reference.md).

# assay-mcp CLI reference

Look up the supported assay-mcp commands, flags and terminal requirements.

Start with `status` to inspect your current connection and `doctor` to check local configuration:

```sh
npx -y @goassay-ai/mcp status
npx -y @goassay-ai/mcp doctor
```

Every command below runs the latest published package. Commands printed by assay-mcp include its exact version, such as `@goassay-ai/mcp@<version>`; both forms work. **Terminal required** means both stdin and stdout must be interactive terminal streams. Other commands do not enforce that requirement, though sign-in and wallet approval still need your participation.

## Inspect and diagnose

| Command                                            | Purpose and flags                                                                                                                                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx -y @goassay-ai/mcp status [--profile <name>]` | Show sign-in, agent, payment-key status, local caps and spending, paid URLs and recorded installs for the profile. Does not renew an expired token.                                         |
| `npx -y @goassay-ai/mcp doctor [--profile <name>]` | Check project configs, the terminal environment, local opt-ins and keychain availability. Changes no files. Exit 0 means no problems; exit 1 means problems were found or the check failed. |
| `npx -y @goassay-ai/mcp --version`                 | Print the package version to stdout.                                                                                                                                                        |
| `npx -y @goassay-ai/mcp --help`                    | Print top-level usage. `-h` and `help` are aliases in this position.                                                                                                                        |

`status` distinguishes a chain-confirmed payment key from status reported only by Assay. “Can't confirm” or “unknown” does not mean permission is off.

## Sign in and out

| Command                                                                 | Purpose and flags                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `npx -y @goassay-ai/mcp login [--profile <name>] [--url <url-or-path>]` | Print and open the approval link. A fresh sign-in replaces the profile's current connection. `--url` selects the deployment using the same origin checks as `serve`; it defaults to the profile's deployment.                                          |
| `npx -y @goassay-ai/mcp logout [--profile <name>]`                      | Attempt to revoke the sign-in, then delete local tokens, payment key, spending state and settings. Keep limits and paid URLs. Applies to all servers using this profile. Does not revoke the key's on-chain permission; read the printed instructions. |
| `npx -y @goassay-ai/mcp enable-paid [--profile <name>]`                 | Print and open the approval page for an existing key. It cannot create the key or approve a wallet signature for you.                                                                                                                                  |

For the approval steps, see [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md) and [How paying works](/developers/use-tools-get-started/how-paying-works.md).

## Manage client entries

| Command                                                                                                                                                          | Purpose                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx -y @goassay-ai/mcp add <url-or-path> [--client <id>] [--name <name>] [--scope user\|project] [--profile <name>] [--force] [--log-file <absolute-path.log>]` | Install one URL in a client. Defaults to user scope and profile `default`. An existing matching install is kept unless you request another name or force replacement.                    |
| `npx -y @goassay-ai/mcp list`                                                                                                                                    | List installs written by `add` and compare each with its client config: `ok`, `missing`, `changed` or `unreadable`. Takes no flags.                                                      |
| `npx -y @goassay-ai/mcp remove <name> [--client <id>] [--scope user\|project]`                                                                                   | Remove an entry written by the helper and its install record. Specify client and scope to resolve ambiguity. Edited entries are left for you to remove in the client. Does not sign out. |

| `add` flag                       | Meaning                                                                                                                                                                                                   |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--client <id>`                  | One of `claude-code`, `codex`, `cursor`, `vscode`, `windsurf`, `gemini`, `claude-desktop`. If omitted, use the only detected client CLI or choose interactively; otherwise the helper asks for this flag. |
| `--name <name>`                  | Override the suggested short server name. Start with a lowercase letter and use lowercase letters, digits and hyphens. The helper also checks the client's tool-name budget.                              |
| `--scope user\|project`          | Select user settings or the current project. Supported scopes vary by client.                                                                                                                             |
| `--profile <name>`               | Use a separate local sign-in and safety state.                                                                                                                                                            |
| `--force`                        | Replace a conflicting named entry, or reinstall the matching entry. Does not approve payments.                                                                                                            |
| `--log-file <absolute-path.log>` | Pass a log file to the installed server. User scope only.                                                                                                                                                 |

`list`, `remove` and `status` see only entries written by `add`. They do not see an entry you added by hand from [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md).

`add` can run without a terminal if the client is explicit or unambiguous. Only an interactive user-scope install offers to allow paid calls, requiring you to type the profile name. Project scope never adds that permission. See [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md) for scope restrictions, including Windows.

## Payment permission and limits

| Command                                                                                                                                                    | Purpose                                                                                               | Interactive terminal |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------- |
| `npx -y @goassay-ai/mcp allow-paid <url-or-path> [--profile <name>]`                                                                                       | Allow this canonical path and query for paid calls. New permissions ask you to type the profile name. | Required             |
| `npx -y @goassay-ai/mcp disallow-paid <url-or-path> [--profile <name>]`                                                                                    | Remove paid permission for this URL. Free calls keep working.                                         | Required             |
| `npx -y @goassay-ai/mcp limits [--profile <name>]`                                                                                                         | Show local per-call, rolling-day, confirmation and provider settings.                                 | Not required         |
| `npx -y @goassay-ai/mcp limits set --per-call <usd> --per-day <usd> [--confirm-above <usd-or-off>] [--providers <address-list-or-off>] [--profile <name>]` | Change local signing limits. Does not change on-chain caps.                                           | Required             |

| `limits set` flag                   | Meaning                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--per-call <usd>`                  | Required non-negative dollar amount, at most six fractional digits. Must not exceed `--per-day`.              |
| `--per-day <usd>`                   | Required non-negative dollar amount for the local rolling 24-hour window.                                     |
| `--confirm-above <usd-or-off>`      | Prompt above this amount, or disable prompts with `off`. Omit to preserve the current value.                  |
| `--providers <address-list-or-off>` | Comma-separated payee addresses, 1–100 entries, or `off` for unrestricted. Omit to preserve the current list. |

Inspect allowed URLs with `status`; there is no `paid-urls` command. See [Spending limits](/developers/use-tools-get-started/spending-limits.md) and [Access policy](/developers/use-tools-advanced/access-policy.md) for how these settings affect calls.

## Run the MCP server

Your AI client normally launches this process and communicates over stdio. Omitting `serve`, including starting with a serve flag, starts the same server.

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

| Flag                             | Default                          | Meaning                                                                                                                                                                        |
| -------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--url <url-or-path>`            | `/` on the built-in Assay origin | Select one MCP URL.                                                                                                                                                            |
| `--name <name>`                  | No explicit name                 | Match the client entry's server name, used for tool-name length handling. At most 56 characters, starting with a lowercase letter; lowercase letters, digits and hyphens only. |
| `--profile <name>`               | `default`                        | Select local sign-in, key and safety state.                                                                                                                                    |
| `--no-paid`                      | Off                              | Never sign a payment from this process.                                                                                                                                        |
| `--log-level <level>`            | `warn`                           | `error`, `warn`, `info` or `debug`.                                                                                                                                            |
| `--log-file <absolute-path.log>` | None                             | Also append diagnostic logs to a local file.                                                                                                                                   |

Profile names start with a lowercase letter or digit and use lowercase letters, digits and hyphens, up to 32 characters. `--profile` is supported only on the commands that show it above. It is not a global flag for `list` or `remove`.

## Environment and headless use

| Variable        | Meaning                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ASSAY_API_KEY` | An agent API key (`assay_sk_live_…`). When set, the server uses it instead of the browser sign-in. It is read only from the environment, never from a flag or file. Create one under the agent's **Keys** in Assay; see [Manage agents, connected apps and payment keys](https://docs.goassay.ai/use-tools/manage-agents-apps-and-keys). `add --scope project` refuses to run while it is set. |

`assay-mcp` always needs an OS keychain: macOS Keychain, Windows Credential Manager or Linux Secret Service. This holds even with `ASSAY_API_KEY`, because the payment key lives there. Machines without a keychain, such as CI runners and containers, are not supported yet.

## Check it worked

Use `list` after changing client entries, and `status` for the intended profile after changing local permissions. Restart the client after an install. General exit codes are 0 for completion, 1 for a failure, and 2 for usage errors or terminal-only refusals. Cancelling a typed confirmation returns 0 with **Nothing changed.**; inspect state to confirm a change.

<details>

<summary>Optional: allow a network proxy from your environment</summary>

| Command                                                                        | Purpose                                                                                                               | Interactive terminal |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `npx -y @goassay-ai/mcp settings [--profile <name>]`                           | Show whether an environment HTTP proxy is allowed; refused by default.                                                | Not required         |
| `npx -y @goassay-ai/mcp settings set --allow-env-proxy on [--profile <name>]`  | Allow environment proxy settings for this profile after typing its name. Only enable a proxy you configured yourself. | Required             |
| `npx -y @goassay-ai/mcp settings set --allow-env-proxy off [--profile <name>]` | Restore refusal of environment proxy settings.                                                                        | Required             |

This opt-in covers variables such as `HTTPS_PROXY`, `HTTP_PROXY`, their lowercase forms and Node's environment-proxy setting. It does not allow disabled TLS certificate checks. See [Security model](/developers/use-tools-advanced/security-model.md).

</details>

<details>

<summary>Optional: log-file rules</summary>

Use an absolute path ending in `.log`, with an existing parent directory. Symlinks and another user's files are refused. An existing file must start with `# assay-mcp log v1`; the MCP will not append to an arbitrary file. On POSIX, log files are private to your user. Normal command output and logs use stderr; stdout is reserved for MCP messages and `--version`.

</details>

## Errors

| Reason                           | Fix                                                                              |
| -------------------------------- | -------------------------------------------------------------------------------- |
| Unknown option or missing value  | Use the flags for that specific command. The help aliases are top-level only.    |
| Interactive terminal required    | Run the setting change yourself in a terminal with stdin and stdout attached.    |
| Existing config cannot be parsed | Correct it in the client; the helper refuses to rewrite malformed configuration. |

## Go further

* [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md)
* [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md)

## Next

* [Troubleshooting](/developers/use-tools-advanced/troubleshooting.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-advanced/cli-reference.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.