Skip to main content Skip to content

MCP server

Connect Cursor, Claude, VS Code, or any MCP client to ZopDay. Ask about services, deployments, environments and live cloud state in plain language.

14 min read

The ZopDay MCP server lets an AI assistant read your workspace directly. Ask Claude “which services failed their last three deploys?” and it queries your live projects, deployments, and cluster state instead of guessing.

It speaks the Model Context Protocol over Streamable HTTP. Setup steps for common clients are below. Any other MCP-capable client connects the same way: use the Other tab.

Before you start

You need:

  • A ZopDay user account in the organisation. The assistant acts with your role, so it sees only what you can see in the app.
  • Access to the MCP Server section, or a colleague who has it: a user who can see the MCP Server section in Settings → Organisation can switch the MCP server on and change Write access.
  • An MCP client that speaks Streamable HTTP, such as Cursor, Claude Code, Claude, VS Code, or Codex (each has a tab below). For OAuth, 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 → Organisation, scroll to the MCP Server section, and switch the toggle on. The badge changes from Inactive to Active and the server URL appears. Only a user who can see the MCP Server section can switch it on.

  2. Copy your server URL

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

The same MCP server serves both products; in ZopNight the equivalent settings are at Settings → Organization (MCP Server section) and Settings → API & MCP → API Tokens / Connected Apps.

Choose how to sign in

You can authenticate in two ways. Every client below supports OAuth; all except Claude Desktop also accept a Personal Access Token.

OAuth

Recommended. There is no token to copy or secret to store. Sign in once in a browser window and your client is connected. Sessions appear on Developer Settings → Connected Apps, where you can revoke them at any time.

Personal Access Token

For CI, servers, or clients that can’t open a browser. Create a long-lived token in Developer Settings and pass it as an Authorization: Bearer header.

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 ZopDay, you approve the connection once, and the client stores refreshable tokens itself.

Option 2: Personal Access Token

  1. Open Developer Settings

    Click your profile avatar at the bottom-left of the sidebar, then Developer Settings.

  2. Create the token

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

  3. Copy it once

    The token is shown only once. Copy it straight into your secret manager, not into a committed file. The config blocks below call it MCP_PAT.

ZopDay Developer Settings on the API Tokens tab, listing personal access tokens with their name, token prefix, the organisation each is scoped to, expiry, creation date, and last-used time, with rotate and revoke actions and a Create Token button

Developer Settings → API Tokens: the tokens that authenticate the API and your AI assistants over MCP, each scoped to the organisations and write capabilities you pick.

A token acts as you, limited to the organisations and write capabilities you pick when you create it. Each call resolves your live role at the moment it is made, so a token can never do more than you can. Create it as the person with the narrowest role that can do the job, and pick only the organisations and write access the client needs.

Set up your client

Find your client below and follow its steps. Most cards cover both OAuth (the recommended one-click sign-in) and Personal Access Token (for CI, servers, and clients that can’t open a browser); pick the tab that matches how you want to authenticate. Claude Desktop connects with OAuth only.

Client

Configure your MCP client to connect to your workspace.

Install in one click:

Add to Cursor

Or set it up manually:

  1. Open the MCP servers panel

    In Cursor, open Customize → MCPs → New MCP server. Cursor opens ~/.cursor/mcp.json for editing.

  2. Paste the config

    Pick OAuth (recommended) or a Personal Access Token; the tabs below toggle the config.

    OAuth (recommended)
    {
      "mcpServers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "transport": "streamable-http"
        }
      }
    }
    Personal Access Token
    {
      "mcpServers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "transport": "streamable-http",
          "headers": { "Authorization": "Bearer MCP_PAT" }
        }
      }
    }

    For PAT, swap MCP_PAT for the token you copied at Developer Settings → API Tokens.

  3. Save and enable

    Save the file. Back on the MCPs panel, click the new zopdev entry and turn the User (~/.cursor/mcp.json) toggle on.

  4. Reload and authenticate

    Click Reload on the zopdev entry. OAuth opens a browser window to sign in; approve to finish. PAT users skip this: the token authenticates every call. The tools appear inside Cursor on the next call.

  1. Add the server

    Inside a Claude Code session, pick OAuth (recommended) or a Personal Access Token; the tabs below toggle the command. The -t http flag is required. Without it, Claude records the URL as a program to execute.

    OAuth (recommended)
    claude mcp add zopdev https://api.zop.dev/mcp-server -t http
    Personal Access Token
    claude mcp add zopdev https://api.zop.dev/mcp-server -t http -H "Authorization: Bearer MCP_PAT"

    For PAT, swap MCP_PAT for the token you copied at Developer Settings → API Tokens.

  2. Restart Claude

    Quit Claude Code and start a fresh session with claude. The new MCP server is picked up on startup.

  3. Authenticate

    In the session, run /mcp, find the zopdev entry, and select Authenticate. OAuth opens a browser window to sign in; approve to finish. PAT users skip this: the header authenticates every call.

  1. Open the custom connector form

    In Claude Desktop, click your profile → Settings → Connectors → Add → Add custom connector.

  2. Fill in the details

    • Name: zopdev
    • Remote MCP Server URL: https://api.zop.dev/mcp-server

    Then click Continue.

  3. Add and connect

    Claude Desktop shows a few security-verification prompts. Accept each one, then click Add to save the connector. Click Connect, and OAuth opens a browser window to sign in. Approve to finish.

Install in one click:

Add to VS Code

Or set it up manually:

  1. Open the MCP config file

    In VS Code (1.99+), open the Command Palette (Cmd + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux), type MCP, and pick the command that opens your user MCP config file (labelled something like MCP: Open User Configuration). To scope the server to one project instead, create .vscode/mcp.json in the workspace root.

  2. Paste the config

    Pick OAuth (recommended) or a Personal Access Token; the tabs below toggle the config.

    OAuth (recommended)
    {
      "servers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "type": "http"
        }
      }
    }
    Personal Access Token
    {
      "servers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "type": "http",
          "headers": { "Authorization": "Bearer MCP_PAT" }
        }
      }
    }

    For PAT, swap MCP_PAT for the token you copied at Developer Settings → API Tokens.

  3. Save and authenticate

    Save the file. VS Code starts the server automatically and shows a ✓ Running · Stop · Restart · More… inlay hint above the zopdev entry. On the first tool call, OAuth opens a browser window to sign in; approve to finish. PAT users skip this: the header authenticates every call.

    You can also manage the server from Extensions → MCP Servers - Installed → zopdev.

  1. Add the server

    Inside a Codex CLI session, pick OAuth (recommended) or a Personal Access Token; the tabs below toggle the command.

    OAuth (recommended)
    codex mcp add zopdev --url https://api.zop.dev/mcp-server
    Personal Access Token
    export ZOPDEV_MCP_PAT=<your token>
    codex mcp add zopdev --url https://api.zop.dev/mcp-server --bearer-token-env-var ZOPDEV_MCP_PAT

    Copy <your token> from Developer Settings → API Tokens and export it in the shell before you launch Codex. Codex reads the env var by name at connect time.

  2. Authenticate

    Run codex mcp login zopdev and follow the prompts. OAuth opens a browser window to sign in; approve to finish. PAT users skip this: the bearer env var authenticates every call.

  1. Open your client's MCP config

    Any client that speaks the standard MCP JSON config works. Find its config file or MCP settings UI in its docs.

  2. Check the field names

    Some clients use serverUrl instead of url, or type instead of transport. The URL and header values below stay the same; only the surrounding key names change.

  3. Paste one of these configs

    Pick OAuth (recommended) or a Personal Access Token; the tabs below toggle the config.

    OAuth (recommended)
    {
      "mcpServers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "transport": "streamable-http"
        }
      }
    }
    Personal Access Token
    {
      "mcpServers": {
        "zopdev": {
          "url": "https://api.zop.dev/mcp-server",
          "transport": "streamable-http",
          "headers": { "Authorization": "Bearer MCP_PAT" }
        }
      }
    }

    For PAT, swap MCP_PAT for the token you copied at Developer Settings → API Tokens.

  4. Save and connect

    Save the config and restart the client. On the first tool call, OAuth opens a browser to sign in; approve to finish. PAT users skip this: the header authenticates every call.

Confirm it works

Start a fresh session and ask:

Terminal window
List my organisations

A working connection calls list_organisations and reads back your organisations by name. Run this before asking anyone for help. It tests the connection on its own: list_organisations is the only tool that 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 server has 332 tools: 185 read and 147 write. For ZopDay, the tools cover everything you need to ship: projects, environments and services, deploys, infrastructure, provisioning, database migrations, and cluster components. By area, with examples:

AreaCoversFor example
Organisations & permissionsThe organisations you can reach and what your own token may dolist_organisations, get_my_permissions
Projects, environments & servicesThe Project → Environment → Service hierarchy, where each environment runs (ZopCloud or your own account), and per-service statuslist_projects, list_environments, list_services, get_project_stats
DeploysDeploy history, shipping a new service or a new revision, rolling back, and following a deploy to activelist_deploys, deploy_service, redeploy_service, rollback_service, wait_for_deploy
Debugging a deployBuild output, live replica logs, and a one-call diagnosis of a failed or stuck deploydiagnose_deploy, get_build_logs, get_service_logs
Infrastructure & provisioningClusters, VM pools, and datastores on one list, provisioning jobs and their step progress, retrying a failed joblist_infrastructure, list_provisioning_jobs, get_provisioning_job_overview, retry_provisioning_job
ComponentsThe Helm and VM component catalogue, installing a component, and moving an installed one to a pinned versionlist_infrastructure_components, install_infrastructure_component, upgrade_infrastructure_component
Database migrationsCopies of a database between Cloud SQL instances, with per-step statuslist_migrations, start_migration, retry_migration
AuditThe audit trail, including every call an assistant makeslist_audit_logs

The same server also carries the ZopNight tools (resources, cost, recommendations, schedules, budgets, and the tags ZopNight derives); see the ZopNight MCP page.

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 rather than the whole tool list.

Start with two tools:

  • list_infrastructure shows every cluster, VM pool, and datastore on one list, the same board as the Infrastructure page.
  • diagnose_deploy answers “why did this deploy fail?” in one call. It reads the stage-by-stage deploy trail, the build output, and what the running replicas are printing.

Reads and writes

Most tools read. A smaller set writes: it deploys or rolls back a service, starts or retries a provisioning job, installs a component, or, on the ZopNight side, changes a schedule or a budget.

One setting per organisation, Write access in Settings → Organisation, controls how much an agent may change. The levels are cumulative, so each level also admits every level below it:

Write accessAdmitsFor example
Read-onlyNothing. Read tools only.None
Metadata onlyRecords inside the platform. No cloud state, no cost.Budgets, recommendation status, smart-tag acceptance
Reversible changesBounded blast radius, may affect cost.Schedules, overrides, tagging policies
Irreversible changesNo undo, or incurs cost.Starting and stopping resources

Every organisation starts at Read-only. Irreversible changes need a token bound to a single organisation. ZopDay deploy, rollback and provisioning tools follow the same tiers; the tool list shows what your level allows.

Writes must also be switched on for the service as a whole, and that switch is off by default; if a write tool never appears even after you raise Write access, contact support. Role and member management (roles, 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.

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

Troubleshooting

List my organisations fails

Check the transport flag, whether the token has expired, and whether the organisation toggle is on. For OAuth, check that you approved the browser prompt. The MCP Server section in Settings → Organisation should show Active; only a user who can see that section can switch it on.

Claude Code tries to run the URL as a program

The server was added without the -t http flag, so Claude recorded the URL as a program to execute. Remove the entry and add it again with -t http.

Calls fail after I revoked an app

If you revoke an app on the Connected Apps page, its subsequent calls fail. Reconnect the client with OAuth, or give it a new Personal Access Token from Developer Settings → API Tokens.

New tools don't show up after setup

Clients pick up newly added tools once per session. Start a new chat on a web client, or open a fresh window or terminal in an IDE, desktop app, or CLI.

Next steps

Authentication

Sign-in methods and Personal Access Tokens.

ZopNight MCP server

The ZopNight tools on the same server: resources, cost, recommendations, schedules, and budgets.

Multi-cloud automation· Production-ready in 30 min· SOC 2 · ISO 27001· 20–60% off the bill, first month· 4 platforms · 1 console· Multi-cloud automation· Production-ready in 30 min· SOC 2 · ISO 27001· 20–60% off the bill, first month· 4 platforms · 1 console·