MCP Server: A Practical Guide

Connect Claude Code, Cursor or VS Code 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. ZopNight’s runs over Streamable HTTP: your client sends JSON-RPC 2.0 over HTTP POST and gets a single JSON response back. It is not SSE and not WebSocket, which matters because the transport setting is the one thing clients get wrong.

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. Every config block below uses it as <server-url>.

Step 1: Enable MCP for your organisation

MCP is off by default for every 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 <server-url> -t http -H "Authorization: Bearer <your-token>"

The -t http flag is required. Without it, Claude Code may attempt OAuth before it tries the header and the connection fails.

Cursor

Settings → Tools & MCP → New MCP Server, then paste:

{
  "mcpServers": {
    "zopnight": {
      "url": "<server-url>",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

VS Code

Create .mcp.json in your workspace, or add the block to your user mcp.json:

{
  "servers": {
    "zopnight": {
      "type": "http",
      "url": "<server-url>",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Codex, Windsurf and Antigravity connect the same way, with the same URL and header.

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 85 read tools. Reads need no extra permission and are checked against your role, so an assistant sees exactly what you would see in the UI.

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 tier, for any role.

Read and write

The MCP server is read-only today. Write operations are refused with mcp_write_not_allowed, and no write tool is advertised to any client, whatever you configure.

34 write tools are built and gated behind a per-organisation write tier in Settings → Organisation, set to None for every organisation including existing ones. Write access is enabled per organisation on request, so contact us if you want to be part of the rollout.

When it does reach you, the tiers are cumulative:

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.

Before you enable any tier, 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 the tier is, and why the default is None.

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. A tool call is authorized the same way the equivalent click in the UI is, with the same answer, and every call lands in the audit trail with a source of mcp.

Where to go next

Full client-by-client setup, the complete tool catalogue, and troubleshooting live in the MCP server documentation.

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.