> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-homepage-20260719-015142.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Your Clients

> Connect Claude Code, Claude Desktop, Codex, and Cursor to a running AgentOS over MCP with one command.

```bash theme={null}
agno connect
```

`agno connect` finds your running AgentOS, configures authentication for each client, writes the client's MCP configuration, and verifies entries it can authenticate immediately. Token-protected endpoints use service-account tokens. OAuth endpoints use client sign-in. Your coding agents can then run your agents, teams, and workflows through the [AgentOS MCP server](/agent-os/mcp/mcp).

The AgentOS must have its MCP server enabled:

```bash theme={null}
uv pip install "agno[os,mcp]"
```

```python theme={null}
agent_os = AgentOS(
    agents=[...],
    mcp_server=True,
)
```

## The Execution Flow

1. **Discover.** An interactive run offers a choice across live env-file, localhost, and previously configured AgentOS URLs. `--url`, an exported `AGENTOS_URL`, and non-interactive runs select one deterministic target. The CLI then reads its version, MCP path, and auth mode from `GET /info`.
2. **Choose authentication.** OAuth-protected MCP endpoints write tokenless entries for one-time client sign-in. Service-account mode resolves an admin credential from `AGNO_ADMIN_TOKEN` or `OS_SECURITY_KEY`, or prompts for it.
3. **Mint when needed.** Service-account mode creates one account per client (named `claude-code`, `cursor`, and so on) with the server's default run and read scopes and a 90-day expiry. An unsecured AgentOS connects without credentials. Pass `--pat` to use service-account tokens with an OAuth-protected endpoint.
4. **Write.** Add an MCP server entry, named after your AgentOS (`agentos` when it has no name), to each client's own config file.
5. **Verify.** Read the entry back the way the client would resolve it. Service-account and unsecured entries complete an MCP `initialize` and `tools/list` call. OAuth entries report `sign in` for the client to complete.
6. **Report.** Print per-client results: `connected`, `sign in`, `already ok`, `skipped`, `action needed`, or `failed`.

When the MCP endpoint is OAuth-protected, nothing is minted: entries are written without tokens and each app completes a one-time sign-in (`sign in` in the report). Pass `--pat` to mint tokens anyway, for headless clients.

Re-runs are safe. Entries that still verify are left alone, and `--skip-existing` never touches anything that exists. Broken or stale entries are rotated after a confirmation prompt in interactive runs; non-interactive runs (`--json` or no TTY) report them as failed instead, so pass `--rotate` in automation.

## Supported Clients

By default `agno connect` configures every client it detects on the machine. Scope the run with `--clients`:

```bash theme={null}
agno connect --clients claude-code,cursor
```

| Client                  | `--clients` value           | Config written                                                            |
| ----------------------- | --------------------------- | ------------------------------------------------------------------------- |
| Claude Code             | `claude-code` (or `claude`) | `~/.claude.json`, or `.mcp.json` with `--project`                         |
| Claude Desktop          | `claude-desktop`            | `claude_desktop_config.json`, launching the `mcp-remote` bridge via `npx` |
| OpenAI Codex            | `codex`                     | `~/.codex/config.toml`                                                    |
| Cursor                  | `cursor`                    | `~/.cursor/mcp.json`, or `.cursor/mcp.json` with `--project`              |
| claude.ai / Claude apps | `claude-ai`                 | None. Prints manual Connector setup steps.                                |
| ChatGPT                 | `chatgpt`                   | None. Prints manual Connector setup steps.                                |

<Note>
  The Claude Desktop entry written by `agno connect` launches the `mcp-remote` bridge over stdio. Node.js must be installed for that entry to start.
</Note>

## claude.ai and ChatGPT

The hosted chat apps add MCP servers from their own cloud, so `agno connect` cannot write or verify anything for them. It prints the setup steps instead:

```bash theme={null}
agno connect --clients claude-ai,chatgpt
```

Requirements:

* The AgentOS must be on a public HTTPS URL. A local AgentOS is unreachable from the apps' clouds; deploy it or expose it through a tunnel first.
* The MCP endpoint must either allow unauthenticated access or expose OAuth. These hosted UIs do not accept an Agno service-account bearer token.
* Paste the printed MCP URL into the app's custom connector or custom app flow. Menu names, plan requirements, and workspace controls vary by provider. Follow the current [Claude custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) or [ChatGPT MCP app guide](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt-beta).

When discovery lands on a public HTTPS AgentOS with authorization disabled, or with an OAuth-protected MCP endpoint, `connect` prints these steps automatically, without `--clients`.

## Options

| Flag              | Default                       | Description                                                                       |
| ----------------- | ----------------------------- | --------------------------------------------------------------------------------- |
| `--url`           | autodiscover                  | AgentOS base URL                                                                  |
| `--clients`       | detected                      | Comma-separated client list                                                       |
| `--name`          | one account per client        | Use one shared service account with this name                                     |
| `--scopes`, `-s`  | server's run + read scopes    | Scope to grant (repeatable)                                                       |
| `--expires`       | `90d`                         | Token lifetime in days, or `never`                                                |
| `--privileged`    | off                           | Required when `--scopes` grants write, delete, admin, or service\_accounts scopes |
| `--pat`           | off                           | Mint tokens even when the MCP endpoint is OAuth-protected (for headless clients)  |
| `--server-name`   | derived from the AgentOS name | MCP server entry name written to client configs                                   |
| `--project`       | off                           | Write project-scoped configs (`.mcp.json` / `.cursor/mcp.json`)                   |
| `--rotate`        | off                           | Revoke and re-mint existing accounts without asking                               |
| `--skip-existing` | off                           | Never touch existing accounts or config entries                                   |
| `--allow-http`    | off                           | Permit credentials over plaintext HTTP to a non-loopback host                     |
| `--yes`, `-y`     | off                           | Trust a remote `AGENTOS_URL` from a `.env` file without prompting                 |
| `--json`          | off                           | Emit a single JSON document                                                       |

## Security

Each client gets its own [service account](/agent-os/security/authorization/service-accounts), so if one token leaks or a client is retired, you can revoke just that one without touching the others:

```bash theme={null}
agno tokens revoke claude-code
```

| Behavior       | Detail                                                                                                                 |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Default scopes | `agents:run`, `teams:run`, `workflows:run`, `sessions:read`, `config:read`                                             |
| Expiry         | 90 days. Override with `--expires 30` or `--expires never`.                                                            |
| Token storage  | Written only to the client's config file (mode `0600`). The CLI stores nothing.                                        |
| Transport      | The CLI refuses to send credentials over plaintext HTTP to a non-loopback host unless you pass `--allow-http`.         |
| Rotation       | After `--rotate`, restart the affected client. A running client keeps its old in-process connection until it restarts. |

## Disconnect

```bash theme={null}
agno disconnect
```

`agno disconnect` removes the AgentOS entry from each client's config. It edits configs only, so it works with the AgentOS stopped and needs no admin credential. Without `--server-name` it removes every entry pointing at the target AgentOS; entries pointing at any other server are never touched. Pass `--revoke` to also revoke the service accounts `connect` minted (this path needs the running AgentOS and an admin credential).

## Scripting

After command-line parsing succeeds, `--json` prints one JSON document with the discovered OS, per-client results, and the exit code. Exit codes: `0` all connected, `1` nothing connected, `2` usage error, `3` partial success. Typer parse errors write to stderr without JSON. JSON mode never prompts. When a run needs to mint or rotate service accounts, export `AGNO_ADMIN_TOKEN` or `OS_SECURITY_KEY` first.

## Developer Resources

* [agnoctl reference](/reference/cli/agnoctl)
* [AgentOS as MCP server](/agent-os/mcp/mcp)
* [Service accounts](/agent-os/security/authorization/service-accounts)
* [Manage tokens with the CLI](/cli/tokens)