Available Tools

The MCP server exposes two classes of tool: reads, available to every connected agent, and writes, which change something and are governed by your organisation's Write access setting and by the caller's OAuth scopes (or PAT capabilities). The first tool, list_organisations, requires no arguments. All other tools require an org_id argument — call list_organisations first to get the org IDs.

Authentication

Every request carries a Bearer token — either an OAuth 2.1 access token (recommended for interactive MCP clients) or a Personal Access Token (for CI and non-browser clients):

Authorization: Bearer <access_token_or_pat>

Key points about authentication:

• Identity is resolved from the token on every call; there is no session
• Permissions are checked dynamically per request, against your live role
• If you are removed from an organisation, access is denied immediately
• If MCP is disabled for an organisation, tool calls for that org are blocked
• OAuth access tokens are short-lived JWTs; refresh tokens rotate on every use with family-kill-on-reuse (RFC 9700 §4.14.2)
• PATs are long-lived, have a configurable expiry, and carry the write capabilities you ticked at mint time
• A token cannot exceed the identity's role — but it can carry less than the identity, bounded by the OAuth scopes granted (or the PAT capabilities ticked)

See How to Connect for the full protocol reference.

What the read tools cover

Reads are available at every level of write access. Each one is still checked against your role: you see through MCP exactly what you would see in the UI.

What the write tools cover

A write tool changes something. Which ones your organisation admits is set by one dial, Settings → Organisation → Write access:

The settings are cumulative — Reversible changes admits the metadata-only tools too. The picker in Settings enumerates the exact tools each setting turns on, generated from the same manifest the gateway authorizes against.

Some surfaces are excluded at every setting and nothing adds them: roles and permissions, user management, organisation deletion, cloud-account deletion, credentials, and bulk actions.

Retries are only partly deduplicated

Every write tool accepts an optional idempotency_key, up to 128 printable ASCII characters. It does two real things: a repeat call carrying the same key replays the original response for 24 hours instead of executing the write again, and two concurrent calls sharing a key are collapsed into a single execution. Reusing a key with different arguments is rejected rather than silently replayed, so a genuine retry is safe and a key collision is loud rather than silent.

Changes are not visible instantly

A write returns when ZopNight has recorded your intent, which is earlier than the world agreeing:

• Schedules and overrides are applied by the scheduler on its next pass — allow about a minute before reading back.
• Deploys and Provisioning jobs are asynchronous. They return an id; poll for status. A deploy routinely runs 20 minutes and can take up to about 35. wait_for_deploy returns after at most 60 seconds with callAgain: true if the deploy is still going — that is normal, and the agent should keep calling.
• Start and stop are confirmed against real cloud state rather than assumed, so a resource can read starting or stopping for a while.

An immediate read-back that shows the old value usually means the change has not landed yet, not that it failed.

Every tool

The complete surface, generated from the gateway's tool manifest. Reads are grouped by area; writes by the level that admits them (see above). The one-line purpose is each tool's own summary — call tools/list for the full argument schema, and remember your own list is filtered to what your token, role, and Write access setting allow.

Reads (165) — available at every tier

Writes (124) — gated by the Write access setting

Pagination

List tools return results in pages — tools/list says which, in each tool's own description. Pass a page argument (starting at 1) to navigate through results. The response includes:

{
"items": [...],
"total": 42,
"page": 1,
"limit": 10,
"hasMore": true
}

When hasMore is true, increment the page number to fetch the next set. If you omit the page argument, the server returns page 1 by default.

Filters Reference

Many tools accept optional filter arguments to narrow results. Pass them in the arguments object alongside org_id. All filters are optional unless noted otherwise.

Filter Example

To list only running AWS compute resources sorted by name:

{
"method": "tools/call",
"params": {
  "name": "list_resources",
  "arguments": {
    "org_id": "your-org-id",
    "provider": "aws",
    "resource_type": "compute",
    "status": "running",
    "sort_by": "name",
    "sort_order": "asc",
    "page": 1
  }
}
}

Example Prompts

Once connected, try asking your AI assistant: