The ship surface: what an assistant can reach

Outcome

By the end of this lesson, you will be able to name the objects the ship surface exposes, distinguish them from the resources ZopNight discovers, and predict which questions each surface can answer.

1. Concept

One assistant, several surfaces. The catalogue groups them by area, and two of those areas are the deploy side of the platform:

SHIP        Projects, Environments, Services, Infrastructure, deploys
DIAGNOSE    Metrics, errors, and the state behind a failed deploy or job

The other areas, Explore, Cost, Optimize, Operate and Govern, are the ZopNight side: the estate, what it costs, and what to do about it.

Two objects that describe the same thing

A SERVICE       is what you deployed. It has an image, a port,
                replicas, environment variables, a URL.

A RESOURCE      is what the cloud created to run it. It has a
                type, an account, a region, an hourly cost.

A question about replicas is a ship question. A question about last month’s spend is a cost question. A question like “why is my service expensive” needs both, which is why the two surfaces live behind one assistant.

What ship does not do

The ship surface changes ZopNight’s records and ships deploys. It does not provision your cloud. Registering a cluster that already exists, or removing one, is tier 3 and deliberately separate from everyday deploying.

2. Demo

YOU    "What services do we run in staging, and which one deployed most recently?"
       -> ship: services, environments, deploy history

YOU    "What did those services cost last month?"
       -> cost: the resources behind them, by account

YOU    "Why did the last deploy of hello-api fail?"
       -> diagnose: build output, then the replica log

3. Hands-on (6 min)

1. Ask your assistant to list your projects and environments.
2. Pick one service and ask for its configuration: port, replicas,
   health checks, and the keys of its environment variables.
3. Ask for the same service's cost this month.
4. Notice which question needed which surface, and that you did not
   have to say so.

Do it through MCP. The same task you just did in the console, asked in one sentence.

BEFORE  A ZopCloud or ZopDay account with at least one service deployed, and a ZopNight account on the same cloud.
ASK     "List our services with their last deploy, and tell me what the one in staging costs this month."
CHECK   the answer names both the service and the resources behind it. If it only names one, you asked half the question.

Tools behind it: list_services (read, Ship), get_service_config (read, Ship), list_deploys (read, Ship), get_cost_by_resources (read, Cost). The full catalogue is at zop.dev/learn/mcp-tools.

4. Knowledge check

Q1

Which surface answers “how many replicas is this service running”?

A. Cost
B. Explore
C. Govern
D. Ship

Q2

You ask for an environment variable’s value and get its key with the value redacted. This is because:

A. Your role is too low
B. No tool returns a variable’s value, for any role, at any tier
C. The value is only available during a deploy
D. You need a PAT rather than OAuth

Q3

Registering an existing cluster with the platform sits at tier 3 because:

A. It is expensive
B. It requires a PAT
C. It touches a customer’s cloud inventory and is not something you undo casually
D. It is a read

5. Apply

Before you ask an assistant anything about a deploy, know which product owns the answer. It will route correctly on its own, but you will read the answer better if you know whether you are looking at what you shipped or at what it costs.

KEEP
  one ship question and one cost question about the same service

Related lessons

• L2: Deploying, rolling back, and auto-deploy
• T1.M1.8.L2: The same deploy, asked in one sentence
• T6.M6.5.L1: Read-only forever

Glossary terms touched

MCP · Deployment · Project-scoped MCP · MCP native