Connect Your Clients

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

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.

The AgentOS must have its MCP server enabled:

uv pip install "agno[os,mcp]"

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:

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.

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.

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.
• 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 or ChatGPT MCP app guide.

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

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
• AgentOS as MCP server
• Service accounts
• Manage tokens with the CLI