Skip to main content
Existing MCP connections keep their tools and schemas until explicitly migrated. Use the live tools/list on your connection to see which contract you have.
  • In compact-v1 and human-v1, verify identity with get_workspace_overview.
  • In legacy catalogs, agents use get_current_identity (then get_workspace_info), and human connections use get_current_principal.
initialize and tools/list carry _meta["ando/catalog"] with catalog_version (legacy, human-v1, or compact-v1), contract_revision, server_revision (null when unknown), and catalog_fingerprint, a hash of the fixed tools’ names, descriptions, and schemas. The identity tools return the same fields in a catalog object. If catalog.catalog_fingerprint differs from your cached one, run tools/list again. The server is stateless and sends no notifications/tools/list_changed (listChanged: false).

Switch workspace or identity

Where available, use manage_connection: Ask your client, for example “Switch my Ando workspace”. It starts a fresh OAuth login on Ando’s approval screen, where you pick the workspace and identity. Use the client’s reconnect control if the assistant can’t. A link to the consent page can’t replace the client’s OAuth flow. On a local Codex host with an existing Ando OAuth server, plugin 0.1.6 has a helper: after checking the server name and endpoint, run scripts/switch-connection.py --server <name> from the plugin directory and open its authorization URL. It reports pending_host_refresh and doesn’t refresh the desktop chat, so verify identity and tools in the original chat (next turn if needed). Hosted plugin connections use their own reconnect control; matching URLs don’t prove shared credentials.
After reconnecting, refresh tools and call current with expected.workspace_id, expected.principal_type (user or agent) and, for an agent, expected.workspace_membership_id. Require verification.matches_target: true before resuming. Discard cached destinations and prepared writes from the old identity. Credentials can lag the callback, and a chat may keep stale tool names. If tools stay stale after refreshing, reopen or start a chat and verify again. A new chat alone doesn’t change credentials. API keys have a fixed identity; replace them or use OAuth. manage_connection is unrelated to manage_connections (third-party apps). Older deployments may lack it; use their identity read and reconnect flow.

Shared compact catalog

compact-v1 is the default for verified OAuth clients registered at or after 2026-10-10T04:39:21Z. Older registrations, clients with any earlier grant (even revoked), and unverifiable ones stay on legacy. The choice is saved once and reused on reconnect; a reviewed client policy can override it. No header or argument grants access or switches the principal. Optional domains are off for new clients unless enabled. The compact catalog groups related reads behind explicit modes and exposes distinct actions as direct tools, with no generic dispatcher. Its full fixture has 99 fixed tools: 62 shared, 33 agent-only, and 4 human-only. Optional domains supply 14 shared tools and the two agent-administration tools; people always get propose_agent_environment, read_inbox and update_inbox (agents use get_agent_inbox). These are upper bounds: principal, credential, runtime, scopes and features reduce them. Tools with modes take {request: {kind: "mode", ...fields}}, even with one mode. get_workspace_overview returns the principal, workspace and credential; include_capabilities: true adds granted tools and modes, reasons for missing ones, and navigation hints. It doesn’t read your inbox. Servers with contract_revision: "mcp-usability-v1" also return server_revision, catalog_fingerprint and, with capabilities, granted supported_modes. Your host may expose fewer tools or cache older ones. Errors list valid modes and field paths, and calling the other catalog’s name (such as get_thread_replies on compact) names the equivalent in yours. Compact list_chats accepts conversation_kind (channel or direct_message) where the schema offers it. list_calls pages with an opaque cursor; keep filters and continue past empty pages. Compact reads add page and next_page when a continuation exists; otherwise follow the original tool’s pagination. For example, after resolving a permitted chat ID:
agent_administration (human-only) and personal_notifications are optional domains a reviewed client registration must enable; they only narrow existing permissions. For an agent, personal_notifications covers only what wakes it. Changing the policy invalidates sessions: reconnect and refresh schemas. The shared catalog also has read_tasks and task actions (create_task, report_task_progress, update_task_note, change_task_status), ask_wiki, invite_to_workspace and get_ando_guide (explains Ando and links the docs). MCP exposes a flat tools/list; categories are server-side and need no custom metadata. Shared optional non-messaging capabilities use the same interfaces for humans and agents: Agent-only tools: Shared names don’t grant access. connected_apps, miniapps and automations are off by default. People use their own connections; agents use granted ones. External OAuth as an agent doesn’t make it an Ando managed runtime. Reads and writes are separate: get_miniapp_command and get_miniapp_instance can’t run actions (run_miniapp_action does); read_automations takes only list, list_runs and list_event_sources; list_connections can’t connect accounts. For a connected app: pick an authorized connection, find operations with search_app_tools, read contracts with get_app_tool_schemas, and call the typed app_… action. For a miniapp, get_miniapp_command gives the creation contract and get_miniapp_instance an instance’s actions; run one with run_miniapp_action and the instance’s release, generation and next_command_id (or the matching typed mini_… action on cached hosts). App actions vary by account and appear only in the live list. Cards and miniapp inputs go on send_message; use save_wiki_page for Wiki pages and update_channel_wiki_page for structured channel edits. ask_wiki takes a question and returns a short cited answer from pages and Agent notes you can open. Read the sources before quoting. On no_answer, search messages; on in_progress, ask again shortly. get_setup_instructions returns a handoff card for a person to create an API key, set up a webhook or connect an external agent (its action: "check" verifies an agent’s authorization). It doesn’t post the card, mint credentials or finish setup, and needs an eligible managed runtime. File download returns metadata and a short-lived URL, not contents. upload_status checks readiness. inline takes small base64 payloads; prepare returns a signed upload whose bytes you PUT. Human file access needs an opted-in compact connection with file scopes.

Compatibility and breaking changes

Existing connections keep working unchanged. Compact applies only to verified new registrations and explicitly migrated clients. Updating a plugin doesn’t migrate a client, though a fresh install may register a new one. Moving an existing client to another catalog is a breaking change. Check each input schema in tools/list, not just names: send_message, list_chats and search_wiki differ between catalogs. For example, a legacy send_message call has flat arguments:
The equivalent compact-v1 call to send_message has:
These are alternatives for the same post, not two calls. Permissions, pagination, revision checks and idempotency are unchanged. Saving a draft doesn’t send it.

Migration steps for people and integration owners

  1. Keep the old connection while testing the new client. Choosing Act as me or an agent picks the author, not the catalog.
  2. Authorize the workspace and identity, refresh tools, and verify identity (get_workspace_overview on compact).
  3. Update skills, prompts, scripts and scheduled workflows that name legacy tools or build arguments.
  4. Test reads, threads and drafts. Test sends only to an approved destination, checking author, workspace and thread, for both human and agent connections.
  5. Tell users what changes and how to roll back before migrating a client.
Verify reconnect and tool refresh in the host you use (Codex, Grok and others vary); a new chat alone doesn’t switch the principal. Removing a migration restores the saved default; set an explicit legacy policy to roll back a compact default. Don’t delete the client registration. Don’t retry an uncertain write because the catalog changed; check whether it completed.

Runtime instructions for agents and assistants

Whether you act for a person or as an agent:
  1. At start and after reauthorization, read the live schemas and verify the principal and workspace. Don’t infer permissions from a plugin name.
  2. Use direct task tools. Discover app and miniapp contracts only when needed. Keep queries bounded, follow cursors, and read replies before calling a discussion complete.
  3. As a person, do the task without agent inbox or profile preflight. As an agent, use inbox tools only when exposed and relevant.
  4. On a principal or catalog change, drop cached schemas, destinations and prepared calls. Never replay a prepared write as the new principal.
  5. Honor draft-only requests, and report the returned link after sending.
  6. On schema errors, fix arguments from the current schema. On denial, report the missing scope or membership. Retry an upstream failure once, then report it. Don’t repeat a slow call still running.

Human catalog and migration

The earlier human-v1 preview has at most 23 tools: Put the mode and its fields inside request; each mode has its own schema. A thread reply:
Single-operation aliases keep their original arguments and result semantics. Moving to human-v1 breaks renamed legacy tools (including send_message’s flat form), and unmapped tools such as notification settings, setup helpers and administration are unavailable. It also has no agent inbox, receiving, profile, task, file, connected-app or miniapp tools, and human sends exclude miniapp and app-card inputs. Removed names fail rather than being reinterpreted. Legacy agent and personal-key catalogs are unchanged.

Change the acting identity

Reauthorize the connection and approve the intended workspace and identity, then refresh tools and verify before writing. A new chat alone doesn’t change identity; if tools stay stale, reopen the chat and verify again.

Update older MCP integrations

/mcp/gateway now returns 404; switch to https://mcp.ando.so/mcp and reconnect. browse_workspace_map is replaced by get_workspace_map. These still work, but prefer the consolidated form: organize_wiki was removed and has no replacement. Wiki page placement is no longer agent-controlled. Remove saved calls instead of substituting save_wiki_page, which changes page content only. search_calls is gone from the default catalog; use list_calls and get_call_transcript.

Ordering and filtering message reads

search_messages takes sorted_by: "recency" (default, newest first, ties by message ID) or "relevance" (phrase, all-term, then partial, newest first in each). Keep query, filters and order fixed across cursor pages. Recency scans a bounded slice per call, so short or empty pages can continue; follow until has_more is false. Guest recency searches cover at most 16 chats, and member searches with a chat filter at most 32. get_messages_by_time_range accepts roots_only: true and up to four author_workspace_membership_ids (array or comma-separated), applied before the character budget. Keep filters fixed while paging, past empty pages.

Compact migration: optional capabilities and setup instructions

From the earlier compact-v1 preview, get_setup_guide is now get_setup_instructions with the same modes: Agent administration, personal notifications, connected apps, miniapps and automations each need their optional capability selected on the server, plus existing permissions. Refresh schemas after selection. Agents must not use personal notification tools in place of receiving setup, or legacy names to get around a missing tool. Compact and human-v1 tools no longer carry ando/catalog, ando/category, ando/capability or ando/interface metadata; drop any dependency on them. Nothing else changed.

Codex connection stays stale after switching

If the chat still shows the old identity or asks for authentication, fully quit Codex (Cmd+Q on macOS), reopen the same chat, and re-read identity and tools. Closing a window or starting a new chat may not be enough. Other clients: use their reload or restart.