MCP Server: A Practical Guide

Connect Claude Code, Cursor or Codex to your ZopNight account. Ask about cloud cost, resources, schedules and recommendations in natural language, and the assistant reads live data instead of guessing.

An MCP server (Model Context Protocol) is a stateless proxy that exposes structured tools to an AI assistant. Zop’s runs over Streamable HTTP: your client sends JSON-RPC 2.0 over HTTP POST and gets a single JSON response back, or a Server-Sent Events stream if it asks for one in its Accept header. It is not WebSocket based, which matters because the transport setting is the one thing clients get wrong.

One server covers both products. The same endpoint and the same token carry ZopNight’s cost and resource tools and ZopDay’s deploy, infrastructure and Kubernetes tools; you choose which you care about by what you ask, not by adding a second connection.

The connection URL

ZopNight shows your server URL in two places in the app:

• Settings → Organisation, in the MCP Server section, once the toggle is on
• Developer Settings, on the screen where you create your token

Copy it from either one; that way you always get the right host for your environment. The blocks below call it MCP_SERVER_URL, and your token MCP_PAT.

Step 1: Enable MCP for your organisation

MCP is enabled per organisation, and only an admin (a user with the Organisation Update permission) can turn it on.

1. Log in to ZopNight and open Settings from the sidebar
2. Click the Organisation tab
3. In the Organisation details card, scroll to the MCP Server section, below the created date
4. Toggle the switch to ON

The status badge changes from Inactive to Active, and the server URL appears. If you cannot see the toggle, you are not an admin on that organisation.

Step 2: Create a Personal Access Token

The server authenticates with a personal access token, prefixed zn_pat_.

1. Click your profile avatar at the bottom-left of the sidebar
2. Select Developer Settings
3. Click Create Token
4. Enter a name, for example “Cursor” or “Claude Code”
5. Choose an expiry period
6. Click Create Token, then copy the token immediately

The token is shown once. Store it in your secret manager, not in a committed file.

A PAT carries your identity, not a narrower one. Every call resolves your live role at the moment it is made, so it can do exactly what you can do in the UI, no more and no less. Mint it as the person with the narrowest role that does the job.

Step 3: Configure your client

All three use the same two values: the server URL and the token.

Claude Code

claude mcp add zopnight MCP_SERVER_URL -t http -H "Authorization: Bearer MCP_PAT"

The -t http flag is required. Without it, the URL is treated as a command to run rather than a server to call. Note the URL and token are written literally, with no angle brackets: < and > are redirection operators in most shells and will break the command.

Claude Desktop

Claude Desktop has no config block: claude_desktop_config.json takes only local, command-launched servers, so a remote URL there is ignored. Add it through Customize → Connectors → Add custom connector, then under Request headers add Authorization with the value Bearer followed by your token. The value is sent exactly as typed, so the word Bearer and the space must be there. Custom connectors are in beta and roll out gradually.

Cursor

Open Customize → MCPs → New MCP Server, then paste and save this config (url plus an Authorization: Bearer header):

{
  "mcpServers": {
    "zopnight": {
      "url": "MCP_SERVER_URL",
      "headers": {
        "Authorization": "Bearer MCP_PAT"
      }
    }
  }
}

Codex

Open Settings → Plugins → MCPs → Add. Set Type to Streamable HTTP, Name to zopnight, and URL to MCP_SERVER_URL. Under Headers, add a header with Key Authorization and Value Bearer MCP_PAT — use the Headers section, not the “Bearer token env var” field. Click Save.

Devin

Devin has no config file: open Settings → Configuration → MCP Servers → Add Custom, then paste this block. The field is url:

{
  "mcpServers": {
    "zopnight": {
      "url": "MCP_SERVER_URL",
      "headers": {
        "Authorization": "Bearer MCP_PAT"
      }
    }
  }
}

Grok build

Grok build registers MCP servers from the terminal, the same way as Claude Code:

grok mcp add --transport http zopnight MCP_SERVER_URL --header "Authorization: Bearer MCP_PAT"

Step 4: Confirm it works

Start a new session and ask your assistant:

List my organisations

A working connection calls the list_organisations tool and returns your organisations by name. That is the check to run before you ask anyone for help, because it isolates the connection from everything else: list_organisations is the only tool that needs no arguments, and every other tool takes the org_id it returns.

If it fails, the usual causes are the transport flag, an expired token, or the organisation toggle still being off.

What the assistant can read

The server exposes 165 read tools across both products (part of a 289-tool catalogue — 165 read + 124 write; the write side is covered in the next section). Reads need no extra permission and are checked against your role, so an assistant sees exactly what you would see in the UI. The per-product docs pages count only their own product’s tools, so their totals are smaller; tools/list is always the authoritative answer for a given token.

List tools forward the full filter and pagination set (provider, status, region, search, sort), so the assistant asks precise questions rather than pulling everything and filtering afterwards. Expensive aggregations are served from a short-TTL cache, so repeated questions in one session stay fast.

Your own list is narrower than the catalogue by design. Call tools/list, or ask the assistant what ZopNight tools it has, and what comes back is filtered to what your token and role actually allow. Nothing advertised there will fail with a permission error.

One hard boundary worth knowing before a security review: get_service_config returns a service’s shape, including its environment variable keys with every value redacted. No tool reveals an env var value, at any level of write access, for any role.

Read and write

Most of the surface reads. A smaller set writes: it changes a schedule, sets a budget, ships a deploy, provisions infrastructure.

How much an agent may change is one setting per organisation, Write access, in Settings → Organisation. The levels are cumulative: choosing one admits everything below it.

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

Before you raise it, read one thing: enabling MCP write means any content in your cloud environment becomes a potential instruction to your agent. Resource names, tags and descriptions are strings other people can influence, and a read tool hands them to a model that can call write tools. The control that matters is how much authority the agent has, which is what this setting is.

How the permissions actually resolve

Every check happens at the gateway on the way in, which is the same place the UI’s own calls are checked.

1. The gateway validates the PAT and identifies your email
2. The assistant calls list_organisations to discover which organisations you belong to
3. The gateway confirms MCP is enabled for the organisation you asked about
4. It confirms you are a member of that organisation
5. It checks the call against your live role, and against the write tier if the tool changes something
6. Results come back as JSON

The MCP server owns no authorization logic of its own; the gateway decides, against the same policy table the UI’s own calls resolve against. Because your role is read per request, revoking access in the app takes effect on the assistant’s next tool call. Every write lands in the audit trail with a source of mcp and the tool that made it.

Where to go next

Full client-by-client setup, the complete tool catalogue, and troubleshooting live in the docs, split by product: ZopNight MCP server for cost, resources and scheduling, and ZopDay MCP server for projects, deploys, provisioning and Kubernetes. Both describe the same endpoint.

If you are evaluating ZopNight itself rather than the integration, the platform comparison covers how it differs from dashboard-first tools, and you can book a demo to see the estate side.