> 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/urls-and-profiles.md).

# URLs and profiles

Connect another MCP URL while keeping paid permission and account profiles separate.

Keep `/` for the general Assay connection. Each local MCP process connects to one URL. To use another tool set alongside it, add another server entry with its own name.

For example, if your account already has a tool set with slug `research`, install it in Claude Code:

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

Restart the client after adding the entry. A user-scope install may ask you to type your profile name to allow paid calls through this URL. That permission is separate from [wallet approval](/developers/use-tools-get-started/how-paying-works.md).

## Choose a URL

Paths below resolve on `https://mcp.goassay.ai`. You can pass a path or its full Assay URL.

| Path                | What it serves                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| `/`                 | General catalogue, with search-based discovery by default. It still respects the agent's access rules. |
| `/my/research`      | Your organization's tool set draft, including its current entries and rules.                           |
| `/my/research@2`    | Published version 2 of that tool set. The version must exist.                                          |
| `/@acme/research`   | Latest publicly shared version of that handle's tool set.                                              |
| `/@acme/research@2` | Version 2, if still available through the public sharing path.                                         |

`research`, `acme` and `2` are examples: use the slug, handle and version from the URL you intend to connect. A version pin fixes the tool set snapshot, not the availability of a provider or permission to use the tools. Shared URLs can stop being served when sharing ends.

## Allow paid calls per URL

Run these yourself in an interactive terminal:

```sh
npx -y @goassay-ai/mcp allow-paid /my/research
npx -y @goassay-ai/mcp status
```

At the confirmation prompt, type the profile name shown in the prompt (`default` unless you passed `--profile`). Read **Paid URLs** in `status` to check the result.

Permission matches the canonical path **and query**, not every URL under the host. Allowing `/` does not allow `/my/research`, and allowing an unversioned tool set URL does not allow its `@2` URL. The built-in default list contains `/`. You can remove it too:

```sh
npx -y @goassay-ai/mcp disallow-paid /
```

Removing paid permission leaves free calls working. `--no-paid` on a running server also prevents that process from signing, even when its URL is allowed. All servers using one profile share that profile's local budget and payment key.

## Check it worked

`list` shows each installed name, client, scope, URL and status. `status` shows paid URLs for the selected profile. A free call through a new URL can work before you allow payments; a paid attempt then says **Paid calls through this server are off.**

<details>

<summary>Optional: use several accounts on one computer</summary>

Use a named profile for a separate sign-in, payment key, local limits, paid-URL list and spending record. Sign in to the intended Assay account and choose its agent when approving each connection:

```sh
npx -y @goassay-ai/mcp login --profile work
npx -y @goassay-ai/mcp add / --client claude-code --profile work --name assay-work
npx -y @goassay-ai/mcp status --profile work
```

Omitting `--profile` means `default`. Profile names start with a lowercase letter or digit, contain lowercase letters, digits and hyphens, and have at most 32 characters. There is no profile-switch command: pass the same name to each relevant command or server entry.

Profiles separate settings; they do not isolate one program running as your OS user from another. Nor do they increase the agent's server-side or account-wide on-chain caps. Signing out one profile affects every local server using it and keeps its local limits and paid-URL choices for the next sign-in.

</details>

<details>

<summary>Optional: install for a project</summary>

Run from the project directory:

```sh
npx -y @goassay-ai/mcp add / --client cursor --scope project
npx -y @goassay-ai/mcp doctor
```

Project scope is supported by Claude Code, Gemini CLI, Cursor and VS Code. Codex CLI, Windsurf and Claude Desktop support user scope only. On Windows, the helper refuses project scope through the Claude Code or Gemini CLI executable; use a file client such as Cursor or VS Code.

Project installs follow these rules:

* Only the built-in Assay origin is accepted.
* `ASSAY_API_KEY` must be unset (see [CLI reference](/developers/use-tools-advanced/cli-reference.md#environment-and-headless-use)), and `--log-file` is refused.
* An explicitly named profile must already exist on this computer. The default profile can sign in on first use.
* Installing does not add paid permission. It can pay through any URL the profile already allows, including `/` by default. Other URLs remain free-only until you allow them in a terminal.
* **When a file-based install backs up an existing config to `.bak`, do not commit the backup.**

Review the command and environment before approving a project server in your client. A project can preload code before the MCP starts; see [Security model](/developers/use-tools-advanced/security-model.md).

</details>

<details>

<summary>Optional: other views and query filters</summary>

| Form                                  | Meaning                                                                                                         |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `/c/weather`                          | Listed tools in a category.                                                                                     |
| `/@acme`                              | Listed provider tools from one maker.                                                                           |
| `/u/<token>` or `/u/<token>@2`        | Latest link-shared version, or a specific shared version. Treat the link as private to its intended recipients. |
| `?tools=get_weather`                  | Narrow to named tools; `get_weather@2` selects a contract major version.                                        |
| `?category=weather`                   | Narrow by category.                                                                                             |
| `?free=1`                             | Force free calls.                                                                                               |
| `?discovery=auto`, `full` or `search` | Select how tools are discovered.                                                                                |

Quote URLs containing query punctuation in your shell. The canonicalizer sorts and deduplicates filters and removes some default discovery values. Use the URL reported by the helper. A filter narrows what a URL serves; it never grants access outside the agent's policy.

</details>

## Errors

| Reason                                 | Meaning                                               | Fix                                                       |
| -------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| `MCP_URL_NOT_FOUND`                    | The URL is missing or unavailable to this connection. | Check the full path, published version and sharing state. |
| Server name too long or already used   | The client entry cannot use that name.                | Accept a suggested short name, or choose a different one. |
| Paid calls through this server are off | This exact URL is not allowed locally.                | Use the terminal flow above for the correct profile.      |

## Go further

* [Security model](/developers/use-tools-advanced/security-model.md)
* [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md)

## Next

* [Access policy](/developers/use-tools-advanced/access-policy.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/urls-and-profiles.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.