# Connect Your Clients (/cli/connect) ```bash 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](/agent-os/mcp/mcp). The AgentOS must have its MCP server enabled: ```bash uv pip install "agno[os,mcp]" ``` ```python agent_os = AgentOS( agents=[...], mcp=True, ) ``` ## The Execution Flow [#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 [#local-mcp-clients] By default `agno connect` configures every client it detects on the machine. Scope the run with `--clients`: ```bash 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` | The CLI’s local Claude Desktop configuration launches the stdio `mcp-remote` bridge with `npx`, so Node.js must be installed. Account-level remote connectors are a separate setup path. ## ChatGPT and Claude Custom Connectors [#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 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. * Follow the provider’s current setup instructions for [Claude custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) or [ChatGPT MCP connectors](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt-beta), using the printed MCP URL. Availability and required workspace permissions vary by provider and 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`. On an OAuth-enabled endpoint, options that shape a minted token (`--name`, `--scopes`, `--expires`, or `--privileged`) require `--pat`. Omit them to use the client’s OAuth sign-in instead. ## Options [#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 [#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 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 [#disconnect] ```bash 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 [#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 [#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)