mcp

<img src="assets/logo.png" alt="ZopDev" width="72" height="72">

# ZopDev MCP

Cloud cost, inventory and governance on AWS, Azure and GCP — **read-only by default, with
optional scoped writes.**

A hosted, remote Model Context Protocol server that gives an AI assistant grounded access to
your ZopDev organisation's cloud estate: what is running, what it costs, what is wasted, what is
scheduled, who owns it, and what shipped.

Point Claude Code, Claude Desktop, Cursor or Codex at it and ask questions that previously took
six browser tabs and a spreadsheet — *which non-production databases ran all weekend*, *what is
our month-to-date Azure spend*, *show me every open recommendation over $500 a month we can
apply without stopping anything.*

One server covers both ZopDev products:

- **ZopNight** — cloud cost and FinOps: resource discovery, spend analysis, recommendations, budgets, and scheduled start/stop.
- **ZopDay** — build and deploy: projects, services, environments, deploys, rollbacks, databases, and cluster provisioning.

**Remote and hosted — there is nothing to install, build or run.**

| | |
|---|---|
| **Endpoint** | `https://api.zop.dev/mcp-server` |
| **Transport** | `streamable-http` (JSON-RPC 2.0 over HTTP POST) |
| **Auth** | OAuth 2.1 (recommended) or a personal access token |
| **Tools** | 289 — 165 read, 124 write |
| **Default access** | Read-only. Writes are opt-in per organisation and scoped per token |
| **Privacy policy** | https://zop.dev/legal/privacy-policy |
| **Terms of service** | https://zop.dev/legal/website-terms-of-service |

- **Learn more** — https://zop.dev/learn/mcp-server
- **Protocol reference** — https://zop.dev/developer-docs/integrations/mcp-server/overview
- **Claude setup guide** — https://zop.dev/learn/how-to/set-up-zopnight-mcp-for-claude

---

## Before you connect

**MCP is enabled per organisation and is off by default.** An admin (anyone with the
*Organisation Update* permission) turns it on in **Settings → Organisation → MCP Server**, and
chooses a [write access](#write-access) level. That is the one step you may need to ask someone
else for.

Once it is on, most clients will sign you in — there is nothing to copy by hand.

---

## Install

### OAuth — recommended, and no token to copy

Any client that can open a browser discovers the sign-in flow by itself. Add the URL and approve
the consent screen; the client handles registration, PKCE and token refresh.

**Claude Code**
```bash
claude mcp add zopdev https://api.zop.dev/mcp-server -t http
```

**Cursor / Claude Desktop / Codex**
```json
{
  "mcpServers": {
    "zopdev": {
      "url": "https://api.zop.dev/mcp-server"
    }
  }
}
```

**VS Code**
```json
{
  "servers": {
    "zopdev": {
      "type": "http",
      "url": "https://api.zop.dev/mcp-server"
    }
  }
}
```

The `-t http` flag on Claude Code is required — it selects Streamable HTTP transport. Without
it, Claude Code treats the URL as a command to execute rather than a server to call.

On first use you are sent to a ZopDev consent screen listing the scopes requested (`mcp:read`,
`mcp:write`) and the exact write tools each admits. Approve, and you are connected. The client
then appears under **Connected Apps**, where you can revoke it at any time.

### Personal access token — for CI, scripts and non-browser clients

Create one under your profile → **[Developer Settings](https://zop.dev/zopnight/app/developer)
→ Create Token**, ticking the write capabilities it should carry. It is shown once and starts
`zn_pat_`.

```bash
claude mcp add zopdev https://api.zop.dev/mcp-server -t http \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json
{
  "mcpServers": {
    "zopdev": {
      "url": "https://api.zop.dev/mcp-server",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

A PAT carries **your** identity — it can do what you can do, and no more. Every call resolves
your live role, so a role change or removal takes effect on the next request with no re-mint.

### Cline

Open the **MCP Servers** icon → **Remote Servers** tab, enter the URL and pick **Streamable
HTTP**. If you prefer editing the config directly, note that Cline wants an explicit `type`, and
spells it in camelCase:

```json
{
  "mcpServers": {
    "zopdev": {
      "type": "streamableHttp",
      "url": "https://api.zop.dev/mcp-server",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Continue

Continue is configured in YAML rather than JSON, and the auth header goes under
`requestOptions`:

```yaml
mcpServers:
  - name: zopdev
    type: streamable-http
    url: https://api.zop.dev/mcp-server
    requestOptions:
      headers:
        Authorization: Bearer YOUR_TOKEN
```

Omit `requestOptions` if you would rather sign in through OAuth.

### Other clients

Any MCP client supporting a remote server and bearer-token auth works with the same URL.
Per-client guides: [ZopNight](https://zop.dev/docs/zopnight/integrations/mcp) ·
[ZopDay](https://zop.dev/docs/zopday/integrations/mcp)

---

## Verify the connection

Ask your assistant:

```
List my organisations
```

This calls `list_organisations` — the only tool that takes no arguments, which makes it the
cleanest test of the connection itself. Every other tool needs an `org_id` that this one
returns.

Then ask **"What are my ZopDev permissions?"** to see exactly what your session can reach.

---

## Example prompts

Once connected, these work against your own estate. Each one is read-only — nothing below
changes a resource:

- Which non-production databases ran all weekend?
- What is our month-to-date Azure spend, broken down by service?
- Show me every open recommendation over $500 a month we can apply without stopping anything.
- Which resources violate our tagging policy?

---

## What it exposes

Reads cover your estate end to end:

- **Inventory** — resources and parent/child topology, filters, discovery status, per-account permission verdicts, live Kubernetes objects, manifests, pod logs, blast-radius analysis
- **Cost** — overview, trends, breakdowns by provider, region, account, service and resource; per-resource cost history; billing sync health; currency rates; Kubernetes cluster cost splits
- **Attribution** — showback by team and by tag, tag coverage and values, smart tags, unit economics
- **Waste** — recommendations with the evidence that fired them, per-rule and per-resource summaries, the rule catalogue, anomalies with root-cause analysis
- **Scheduling** — schedules and cron windows, resource groups, overrides and override candidates, state history, schedule success rates
- **Governance** — budgets and live spend, audit logs, RBAC policy catalogue and effective permissions, tagging policies and violations, IaC policies and validation runs, watch and alerting policies
- **Automation** — autoscaler policies, events, smart defaults and required permissions; event-readiness plans, checks and cost previews
- **Delivery** — projects, environments, services, deploys, infrastructure, provisioning jobs, service config and diagnostics
- **AI spend** — LLM cost and usage by provider, model and team; virtual keys; AI budgets
- **Org** — teams and members, notification channels and subscriptions, integrations, dashboards, exports

Where a write tier permits them, mutating tools cover budgets, schedules, overrides, resource
groups, start/stop, autoscaler and event-readiness lifecycle, policies, notifications,
integrations, dashboards, provisioning, deploys and remediation workflows.

<!-- TOOLS:START — generated. Do not edit by hand; CI rewrites this block on each mcp-server release. -->

| Category | Tools | Read | Write | What it covers |
|---|---:|---:|---:|---|
| **Introspect** | 4 | 4 | 0 | what your own token can do |
| **Explore** | 24 | 20 | 4 | organisations, cloud accounts, resources, teams, discovery status |
| **Cost** | 58 | 48 | 10 | cost and savings summaries, breakdowns, trends, budgets, billing sync |
| **Optimize** | 21 | 10 | 11 | recommendations and their savings, schedules, overrides, resource groups |
| **Operate** | 55 | 24 | 31 | start/stop history, actions, scheduler events, provisioning jobs |
| **Govern** | 94 | 36 | 58 | tagging policies, smart tags, roles, users, audit logs, notifications |
| **Ship** | 24 | 14 | 10 | projects, environments, Services, infrastructure, deploy status |
| **Diagnose** | 9 | 9 | 0 | metrics, error detail, state behind a failed deploy or job |
| **Total** | **289** | **165** | **124** | |

<!-- TOOLS:END -->

List tools forward the full filter, sort and pagination surface of the underlying API rather
than a reduced subset. `tools/list` is filtered per caller — a tool is advertised **if and only
if** the gate would allow you to invoke it, so an assistant is never shown a capability it
cannot use.

---

## Safety model

The write surface is inert until three separate things are true, and none of them live in this
repository.

- **Read-only by default.** Every organisation starts at write tier `none`.
- **A global kill switch.** `MCP_WRITE_ENABLED` defaults to off, so the write surface is inert until an operator flips it — not merely unadvertised.
- **Four tiers.** `none` (default), 1 metadata-only, 2 reversible, 3 irreversible. Tier 3 additionally requires an organisation-bound token.
- **Gated at the gateway, not here.** Organisation write tier, live RBAC and per-token scope are resolved and enforced at the single ingress that already owns authentication and routing. This server owns no authorization logic and is a stateless executor.
- **Permanently out of scope, at every tier.** Roles and permissions, user management, organisation and cloud-account deletion, credential access, and bulk actions. `get_service_config` redacts every environment-variable value; no tool returns one.
- **Everything is audited.** Reads and writes both land in the audit trail with `source: mcp`. A read never stores its response payload — on success or failure — t