Connect Your Clients

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. 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

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.
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

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.

Get Started

Starters

Apps

Agno CLI

Connect Your Clients

The Execution Flow

Supported Clients

claude.ai and ChatGPT

Options

Security

Disconnect

Scripting

Developer Resources

​The Execution Flow

​Supported Clients

​claude.ai and ChatGPT

​Options

​Security

​Disconnect

​Scripting

​Developer Resources

The Execution Flow

Supported Clients

claude.ai and ChatGPT

Options

Security

Disconnect

Scripting

Developer Resources