> 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/security-model.md).

# Security model

Understand which threats the local MCP protects against and where its protection ends.

{% hint style="warning" %}
Set on-chain spending caps you are comfortable losing if this computer is compromised.
{% endhint %}

Your payment key stays on your computer. Assay can request a payment, but the local process decides whether to sign it.

## What lives where

| Item                                                | Where it lives                                                                     | What it permits                                                                                                 |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| OAuth access and refresh tokens                     | OS keychain                                                                        | Sign in as the agent you approved. Tokens are sent to the built-in Assay services when needed.                  |
| Private payment key                                 | Created locally; stored in the OS keychain and read into the local signing process | Sign payments within its wallet-approved permission. The private key never leaves the computer through the MCP. |
| Public payment-key address                          | Local profile and Assay                                                            | Identify the key and compare its fingerprint during approval. It cannot sign.                                   |
| Local limits, allowed paid URLs and spending record | Private profile files in your OS account                                           | Bound the normal local signing path. These files contain no private payment key or OAuth tokens.                |
| Key permission, expiry and account caps             | Payment contract on Robinhood Chain                                                | Bound redemption of signed USDG payments.                                                                       |

The supported stores are macOS Keychain, Windows Credential Manager and Linux Secret Service. There is no file fallback: a missing or locked keychain blocks startup.

## What each party can do

| Party or threat                              | Protection                                                                                                                                                                                            | Limit of that protection                                                                                                                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assay server, including a compromised server | Cannot obtain the private payment key through the protocol. Requests must pass local checks for the built-in payment destination and asset, quote, key permission, caps, provider and tool.           | The server supplies quotes and tool results. A bad server could mislead the agent or ask for payments that fit every check. Local checks do not prove a result is useful or true.                              |
| AI instructions or a web page                | No MCP tool edits local safety settings. Settings changes require an interactive terminal; wallet approval changes on-chain permission. Server requests are not forwarded as requests to your client. | An AI can still call allowed tools and spend within allowed limits. Prompt injection can waste that budget. An AI with terminal or code-execution access may also cross the local boundary below.              |
| A shared project configuration               | Cannot move the safety files by changing `HOME` or `XDG_CONFIG_HOME`. Certificate-check bypasses are refused; environment proxies require a local opt-in.                                             | Project configs start programs. A Node preload can run before the MCP checks anything. Your client's approval of project servers is essential. Extra certificate authorities produce a warning, not a refusal. |
| Another program running as your OS user      | Normal MCP settings commands refuse piped input. Private profile permissions protect against other users.                                                                                             | This is not isolation from your own programs. They may read the keychain, edit local state, or use a terminal. A terminal check cannot establish that a human is typing.                                       |

On macOS, the keychain access list identifies the `node` binary. Other Node scripts may read the item without a new prompt. A Node upgrade may prompt again; review access before choosing **Always Allow**. On Linux and Windows, a program running as your user can access an unlocked store.

The MCP sends credentials only to built-in Assay hosts and refuses redirects. This limits credential redirection; it does not hide tool arguments from Assay or from the provider serving the call.

## The last line: on-chain caps

A program that steals the payment key can bypass local limits and the local provider list. The payment contract still checks the key's permission, expiry, per-call and spending-window caps, plus the account caps. Keep those caps small enough for that risk. See [Spending limits](/developers/use-tools-get-started/spending-limits.md) for the default bounds and how the windows work.

Signing out deletes this profile's local payment key and tokens. It does **not** cancel the key's on-chain permission. If you suspect a copy exists elsewhere, follow the logout message to **Stop it** in Assay and approve the wallet signature.

## Check it worked

Inspect the current profile and run the configuration checks:

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

Check the reported agent, key fingerprint, local caps and **Paid URLs**. `doctor` reports environment and project-config findings; a clean result cannot prove that the OS user or every program on the computer is trustworthy.

<details>

<summary>Optional: understand revocation and diagnostic logs</summary>

Stopping a key or lowering on-chain caps is not an instant rollback of payments. The contract has a grace period during which a revoked key or the prior caps can still be accepted, bounded by the key expiry. The local proxy refuses an inactive grant once it reads that state; a program holding a stolen key can bypass that local check.

The default log level is `warn`. Logs go to stderr, with an optional local log file. The logger redacts credentials and signatures and excludes tool arguments and results. Logging is a diagnostic aid, not a record of every action taken by other programs under your user account.

</details>

## Errors

| Reason                         | Meaning                        | Fix                                                                                                                                                      |
| ------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keychain unavailable or locked | Secrets cannot be read safely. | Make the OS store available or unlock it, then restart your client.                                                                                      |
| Payment refused                | One local check failed.        | Read the refusal reason; do not bypass the check to complete the call. Review [How paying works](/developers/use-tools-get-started/how-paying-works.md). |

## Go further

* [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md)
* [Spending limits](/developers/use-tools-get-started/spending-limits.md)

## Next

* [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.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/security-model.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.