MCP server

The ZopNight MCP server lets an AI assistant read your organisation’s data directly. Ask Claude “which EC2 instances sat idle last week and what would stopping them save?” and it queries your live resources, costs, and recommendations instead of guessing.

It speaks the Model Context Protocol over Streamable HTTP. The clients below each have their own setup steps; any other MCP-capable client connects the same way, using the Other tab.

Settings → Organization: the MCP toggle, the server URL to paste into your client, and the write-access level that bounds what an assistant may change.

Before you start

You need:

• A ZopNight user account in the organisation. The assistant acts with your role, so it sees only what you can see in the app.
• Permission to update the organisation, or a colleague who has it, to switch the MCP server on and to raise Write access above Read-only.
• An MCP client that speaks Streamable HTTP, such as Cursor, Claude Code, Claude, VS Code, or Codex (each has a tab below). For the OAuth option, the client must be able to open a browser. For CI and headless servers, use a Personal Access Token instead.

Then:

1. Enable MCP for the organisation

   Open Settings → Organization, find the MCP Server section, and switch the toggle on. The badge changes from Inactive to Active and the server URL appears. Only a user with permission to update the organisation sees the toggle.

2. Copy your server URL

   Your server URL is https://api.zop.dev/mcp-server. It’s the same for every organisation. Auth negotiates the org, so you don’t need to look it up in the app.

The same MCP server serves both products; in ZopDay the equivalent settings are at Settings → Organisation (MCP Server section) and Developer Settings (user menu) → API Tokens / Connected Apps.

Choose how to sign in

You have two ways to authenticate. Pick one: every client below supports both, except the Claude desktop app, which connects with OAuth only.

Option 1: OAuth (recommended)

There is nothing to configure up front. Point your client at https://api.zop.dev/mcp-server and let it prompt on the first tool call. A browser tab opens to ZopNight, you approve the connection once, and the client stores refreshable tokens itself.

Option 2: Personal Access Token

Settings → API & MCP → API Tokens: every personal access token with its prefix, organisation, expiry, and last use, and Create Token to mint a new one.

1. Open API & MCP settings

   Open Settings → API & MCP and stay on the API Tokens tab.

2. Create the token

   Click Create Token, name it after the client that will use it (“Cursor” or “Claude Code”), choose an expiry, and confirm.

3. Copy it

   Copy the token when it is created, straight into your secret manager, never into a committed file. Afterwards the list shows only its prefix. The blocks below call it MCP_PAT.

A token acts as you, limited to the organisations and write capabilities you choose when you create it. Every call also resolves your live role at the moment it is made, so it can never do more than you can in the app. Give each token only the organisations and write capabilities its client needs.

Set up your client

Find your client below and follow the steps for it. Each card covers OAuth (the recommended one-click sign-in) and, where the client supports it, a Personal Access Token (for CI, servers, and clients that can’t open a browser; the Claude desktop app is OAuth only). Pick the tab that matches how you want to authenticate.

Confirm it works

Start a fresh session and ask:

List my organisations

A working connection calls list_organisations and reads back your organisations by name. Run this before asking anyone for help: it isolates the connection from everything else, because list_organisations needs no arguments, and most other tools take the org_id it returns.

If it fails, see Troubleshooting below.

What the tools cover

The MCP catalogue has 337 tools: 186 read and 151 write, including the ZopDay deploy and provisioning tools. They are grouped by area below, with a few examples of each:

For the authoritative list, call tools/list or ask your assistant what tools it has. The list is filtered to what your token and role allow, so it shows what you can use, not the whole catalogue.

Start with two tools. get_cost_overview answers “where is the money going” in one call, and get_resource_overview answers everything about one resource, including its metrics, cost history, and recommendations. Each one replaces several narrower calls.

Reads and writes

Most tools read. A smaller set writes: it changes a schedule, sets a budget, accepts a tag, or starts or stops a resource.

How much an agent may change is one setting per organisation, Write access, in Settings → Organization. Every organisation starts at Read-only, so no agent can change anything until someone with permission to update the organisation raises the level. The levels are cumulative, so choosing one admits everything below it:

Two more conditions apply to writes. Irreversible changes also need a token bound to a single organisation. And writes must be switched on for the ZopNight service as a whole; if a write tool never appears in your client’s tool list even after you raise Write access, contact support.

Role and member management (creating, updating and deleting roles, adding, updating and removing organisation members, and team-member changes) is admitted at Metadata only, and bulk start and stop at Irreversible changes. Four capabilities are excluded at every level, and no setting adds them: organisation deletion, cloud-account deletion, credential reads, and org-level role assignment. Assigning a role to a team member is a team-member change, admitted at Metadata only.

An agent can never exceed the permissions of the person whose token it holds. Your role is resolved on every call, so revoking someone’s access in the app takes effect on their next tool call, and every write is recorded in the audit trail.

Troubleshooting

Next steps