tools/list on your connection to see which contract
you have.
- In
compact-v1andhuman-v1, verify identity withget_workspace_overview. - In legacy catalogs, agents use
get_current_identity(thenget_workspace_info), and human connections useget_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, usemanage_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.
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:
compact-v1 call to send_message has:
Migration steps for people and integration owners
- Keep the old connection while testing the new client. Choosing Act as me or an agent picks the author, not the catalog.
- Authorize the workspace and identity, refresh tools, and verify identity
(
get_workspace_overviewon compact). - Update skills, prompts, scripts and scheduled workflows that name legacy tools or build arguments.
- Test reads, threads and drafts. Test sends only to an approved destination, checking author, workspace and thread, for both human and agent connections.
- Tell users what changes and how to roll back before migrating a client.
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:- At start and after reauthorization, read the live schemas and verify the principal and workspace. Don’t infer permissions from a plugin name.
- 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.
- As a person, do the task without agent inbox or profile preflight. As an agent, use inbox tools only when exposed and relevant.
- On a principal or catalog change, drop cached schemas, destinations and prepared calls. Never replay a prepared write as the new principal.
- Honor draft-only requests, and report the returned link after sending.
- 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 earlierhuman-v1 preview has at most 23 tools:
Put the mode and its fields inside
request; each mode has its own schema. A
thread reply:
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 earliercompact-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.