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.
The AgentOS must have its MCP server enabled:
agent_os = AgentOS(
agents=[...],
mcp_server=True,
)
The Execution Flow
- 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.
- Authenticate. When authorization is enabled, resolve an admin credential from
AGNO_ADMIN_TOKEN or OS_SECURITY_KEY, or prompt for it.
- 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.
- Write. Add an MCP server entry, named after your AgentOS (
agentos when it has no name), to each client’s own config file.
- 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.
- 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:
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. |
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.
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:
agno connect --clients claude-ai,chatgpt
- 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.
- Both apps’ Connectors UIs authenticate with OAuth, not bearer tokens, so the AgentOS must be public or OAuth-enabled. A token-protected AgentOS cannot be added from the UI yet.
- 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, so if one token leaks or a client is retired, you can revoke just that one without touching the others:
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
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
