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, 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:

uv pip install "agno[os,mcp]"

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:

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

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

Developer Resources

• agnoctl reference
• AgentOS as MCP server
• Service accounts
• Manage tokens with the CLI