> 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/access-policy.md).
# Access policy
Understand how a URL, agent access and provider restrictions decide which calls can run.
An agent can call a tool only when its MCP URL serves the tool and its access policy allows it. Connecting a broader URL does not expand the agent's permissions. Start by asking the connected client to find the tool you need; discovery already uses both checks.
## How access is enforced
The server checks each call again. A tool list saved by the client cannot grant access after the policy changes.
| Layer | What it decides | Refusal |
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| URL view | Whether this URL serves the tool, including its filters and tool set version. | `TOOL_NOT_IN_TOOLSET` |
| Agent access | Whether the agent may use the tool. Restricted access allows named tools or tools in allowed tool sets. | `TOOL_NOT_ALLOWED` |
| Connection credential | Whether this particular connection narrows the agent's access further. It can only reduce access. | `TOOL_NOT_ALLOWED` |
| Provider rules | Whether an available provider meets the agent's rules and this tool set entry's rules. | `NO_PROVIDER_MATCHES_RULES` when the rules leave none. |
| Local payment guard | Whether the selected payee is in this profile's optional provider allow-list. | G8 refusal before signing. |
The default agent access mode is `ALL`. In `RESTRICTED` mode, a tool may be allowed directly or through an allowed tool set. A tool set grant can require calls to come through that tool set's own URL. In that case, the same tool reached through `/` remains blocked unless another grant allows it there.
For example, an agent allowed to use a research tool set only through its tool set URL must connect that URL. Adding `/` to the client or to the local paid-URL list does not override this server check.
## How provider rules combine
Agent rules apply through every URL. Tool set entry rules apply when you use that tool set's URL.
| Rule | Combined behavior |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Allowed providers on a tool set entry | Only providers in that set are candidates. |
| Excluded providers | Both the agent's exclusions and the entry's exclusions apply. |
| Maximum price | The lower comparable maximum wins. |
| Minimum provider tier | The higher minimum wins. |
| No matching provider | Normally refuse. An entry configured for `FALLBACK_BEST` may drop its own provider preferences, while keeping the agent's rules. |
{% hint style="warning" %}
Minimum quality is not enforced yet. Do not rely on it to restrict providers.
{% endhint %}
The local provider allow-list is a separate payment check. It compares the payee's address, not the server's provider ID, and does not tell the server which provider to choose. The server can select a provider that passes its rules and still receive a local refusal. The local list does not restrict free calls.
## Check the local restriction
```sh
npx -y @goassay-ai/mcp limits
```
`providers: any` means that this local check is unrestricted. Server access and provider rules still apply. For a missing tool, compare discovery through the intended tool set URL with the policy for the agent selected at sign-in.
## Check it worked
A permitted tool appears in discovery when it has routable supply. A direct call to a tool outside the URL or policy is refused by the server even if the client remembers its name. A paid call to a payee outside the local list is refused before signing.
Optional: restrict local payment recipients
In an interactive terminal, use `limits set` with `--providers` followed by a comma-separated list of payee addresses. Both `--per-call` and `--per-day` are required even if you are only changing providers. The list accepts 1–100 addresses. Use the intended providers' verified payee addresses; provider IDs do not work here.
Omitting `--providers` preserves the current list. To remove the local restriction while keeping the default dollar caps:
```sh
npx -y @goassay-ai/mcp limits set --per-call 0.50 --per-day 5 --providers off
```
This example changes the dollar caps too. Use your intended caps if they differ. The command does not change the agent's server-side policy or its wallet-approved caps.
Optional: understand policy versions and tool sets
An allowed tool set can refer to a published snapshot. Your own unversioned tool set grant uses its draft; an unversioned official grant follows its latest public version. Another organization's allowed tool set is pinned to a published version. A new publication does not silently expand that pinned grant.
The server invalidates cached access after changes to policies, connection restrictions or tool set drafts. The next request resolves the updated permissions. A changed tool set URL and a changed access grant are separate decisions; both must allow the tool.
## Errors
| Code or message | Meaning | Fix |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `TOOL_NOT_IN_TOOLSET` | The tool is outside this URL's view. | Use the intended [URL](/developers/use-tools-advanced/urls-and-profiles.md) or correct its filter. |
| `TOOL_NOT_ALLOWED` | Agent or connection access blocks it. | Have the account owner review that access; reconnecting to `/` does not grant it. |
| `NO_PROVIDER_MATCHES_RULES` | Provider rules leave no eligible provider. | Review the rule source in the refusal and choose compatible rules or another tool. |
| **Assay asked for a payment this app refused: the provider is not in the allow-list.** (`G8_PROVIDER_NOT_ALLOWED`) | The payee fails the local payment allow-list. | Review the intended payee and the local restriction yourself. |
## Go further
* [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md)
* [Security model](/developers/use-tools-advanced/security-model.md)
## Next
* [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.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/access-policy.md?ask=&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.