> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.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, mints one service-account token per coding agent when the AgentOS has authorization enabled, writes each client's MCP configuration, and verifies every entry with a real MCP handshake. Your coding agents can then run your agents, teams, and workflows through the [AgentOS MCP server](https://agno-v2.mintlify.site/agent-os/mcp/mcp.md).

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=True,
)
```

## The Execution Flow

1. **Discover.** Resolve the AgentOS from `--url`, `AGENTOS_URL` (the environment variable, or a project `.env.production` / `.env` file), or a localhost probe, then read its version, MCP path, and auth mode from `GET /info`.
2. **Authenticate.** When authorization is enabled, resolve an admin credential from `AGNO_ADMIN_TOKEN` or `OS_SECURITY_KEY`, or prompt for it.
3. **Mint.** When authorization is enabled, create one service 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.
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, then complete an MCP `initialize` and `tools/list` call against the AgentOS with the configured token.
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.

## Local MCP 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` |

> [!NOTE]
>
> Claude Desktop speaks MCP over stdio only, so its entry launches the `mcp-remote` proxy with `npx`. Node.js must be installed for that entry to start.

## ChatGPT and Claude Custom Connectors

ChatGPT and Claude are hosted AI apps. Add AgentOS as a custom connector in each app. Agno Connect cannot edit or verify their settings, but it can print the MCP URL and setup steps:

```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.
* A secured MCP endpoint must use OAuth. A bearer-token-only endpoint cannot be added through these connector UIs.
* In the app, go to Settings -> Connectors -> Add custom connector and paste the printed MCP URL. Custom connectors need a paid plan.

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](https://agno-v2.mintlify.site/agent-os/security/authorization/service-accounts.md), 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

`--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. In `--json` mode the CLI never prompts, so set `AGNO_ADMIN_TOKEN` before you run it.

## Developer Resources

* [agnoctl reference](https://agno-v2.mintlify.site/reference/cli/agnoctl.md)
* [AgentOS as MCP server](https://agno-v2.mintlify.site/agent-os/mcp/mcp.md)
* [Service accounts](https://agno-v2.mintlify.site/agent-os/security/authorization/service-accounts.md)
* [Manage tokens with the CLI](https://agno-v2.mintlify.site/cli/tokens.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.