The embedded agent#
Midnight ships an agent that can operate the control plane, and an MCP server that exposes the same tools to external clients.
Before you start#
- A running Midnight installation.
- A provider credential for the agent. Claude is the default provider; an OpenAI-compatible provider is also supported and drives the same tools.
What the agent can do#
The agent has a tool registry that performs real mutating control-plane actions:
| Tool | Effect |
|---|---|
deploy_from_source |
Deploy a service from source |
redeploy |
Replay an existing deployment |
rollback |
Return a service to its previous deployment |
set_variable, unset_variable |
Change service configuration |
These are real actions with real consequences. An agent with mutations enabled can deploy, roll back and change configuration on your installation.
The mutation gate#
Mutating tools are gated behind an AllowMutations flag and every call is
audited.
Leave mutations disabled for an agent you are using to investigate. Enable them deliberately, for a session where you intend the agent to act, and read the audit record afterwards.
Cost accounting#
Agent calls carry per-call token and cost accounting. The dashboard's agent panel streams chat, tool calls, and a cost footer, so spend is visible while it happens rather than at the end of a billing period.
Prompt caching is applied to the system and tools prefix with a short time to live, which reduces the cost of a sustained conversation.
Automated failure diagnosis#
A diagnosis worker watches deploy and build operation outcomes. When one fails, it calls the model within a bounded time budget, persists a diagnosis conversation, records the diagnosis against the operation, and emits a timeline event that the dashboard renders.
This runs on failure, not on every operation. A deployment that succeeded has no diagnosis attached.
The MCP server#
The same tool registry is exposed over the Model Context Protocol as JSON-RPC 2.0, with:
- a
/.well-known/mcpmanifest; - bearer authentication;
- per-session rate limiting; and
- a mutation gate that refuses disallowed mutations.
An external MCP client can therefore drive the platform with the same tools and the same gate.
The MCP surface is authenticated with a bearer token. Anyone holding that token reaches the tool registry. Scope and rotate it as you would a deployment credential.
Provider choice#
The agent sits behind a provider seam. Claude is one implementation; an OpenAI-compatible provider configured through a base-URL override is another, using the Responses API. Both drive the same registry, so switching provider does not change what the agent can do.
Verify#
- With mutations disabled, a mutating request is refused.
- With mutations enabled, the action happens and an audit entry exists.
- A failed deploy has a diagnosis attached and a timeline event.
- The MCP manifest is reachable at
/.well-known/mcp.
If it does not work#
| Symptom | Check | Recovery |
|---|---|---|
| A mutating tool is refused | The AllowMutations flag |
Refusal with mutations disabled is correct behaviour |
| MCP requests are rejected | The bearer token, and rate limits | Per-session rate limiting applies |
| No diagnosis on a failure | Whether the failure was a deploy or build outcome, and the time budget | Diagnosis is bounded; a slow model call can exhaust it |
| Costs look wrong | The per-call accounting in the agent panel | Cost is recorded per call, including cached prefixes |
| The provider never responds | The base URL override for an OpenAI-compatible provider | An override aimed at the wrong endpoint fails every call |