Available Tools

The MCP server exposes two classes of tool: reads, available to every connected agent, and writes, which change something and are refused unless your organisation has opted into a write tier. 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 must include a valid PAT in the Authorization header:

Authorization: Bearer <your-token>

Key points about authentication:

• Tokens are tied to your email, not a specific organisation
• 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
• Tokens have configurable expiry — create a new one when it expires
• A token can do exactly what you can do — no more, and no less

What the read tools cover

Reads need no write tier. 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, default None:

Tiers are cumulative — tier 2 admits tier-1 and tier-2 tools. The picker in Settings enumerates the exact tools each tier turns on, generated from the same manifest the gateway authorizes against.

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

Writes are off today

MCP write is disabled across the platform while it rolls out. Every mutating tool call is refused with mcp_write_not_allowed regardless of the tier you have set, and no write tool is advertised to any AI tool. Contact us to be part of the rollout.

Retries are not deduplicated

Every write tool accepts an idempotency_key. Nothing reads it today. There is no dedup anywhere behind these tools, and the argument is inert.

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 call_again: 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 tier 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 tier allow.

Reads (85) — available at every tier

Writes (34) — gated by write tier, off by default

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: