Moorhold docs

The portal's MCP server is how an agent works with Moorhold as the person it acts for. It can follow and cancel change proposals, find the tools' own MCP servers, and run declared metrics. Everything an agent does is checked against the person's groups and written to the audit log.

This page describes the tools in the latest release (2026.11.4).

Endpoint POST /mcp on the portal MCP server. On an installed server it listens on 127.0.0.1:8096, so its address is http://localhost:8096/mcp on the server. The Keycloak Component's overrides.mcpUrl sets another public address.
Protocol revisions 2026-07-28 (stateless), 2025-11-25 and 2025-06-18 (with the initialise handshake).
Server name moorhold-portal.
Authorisation Authorization: Bearer <token>, a token from the stack's Keycloak whose audience is the Stack's spec.agents.mcpAudience (shipboard-mcp on an installed server). A token that also names one of the tools' own MCP audiences is refused.
Origin A request with an Origin header is refused with 403 unless that origin is allowed. Agents that send no Origin aren't affected.
Request size Up to 1,000,000 bytes. A larger body gets 413.

A missing or invalid token gets 401 with WWW-Authenticate: Bearer resource_metadata="<server>/.well-known/oauth-protected-resource", error="invalid_token". The resource metadata names the stack's Keycloak as the authorisation server. The HTTP endpoints reference lists the server's other routes.

tools/list lists only the tools the signed-in person may use, so a person outside the Stack's proposer groups doesn't see propose_source. The metric tools are listed only on a stack with the warehouse, which every installed server has.

propose_source, get_proposal and cancel_proposal return a proposal, and list_proposals returns a list of them, each with these fields:

Field What it is
proposal The proposal's name (the proposal field). Use it to refer to the proposal.
phase pending_approval, approved, applied, rejected, withdrawing, withdrawn or removed.
target The resource it changes, for people to read.
proposedBy The user and client that proposed it.
reason Why, or null.
plan What applying it would do, a list of adapter, action and description, or null until the reconciler has made the plan.
decision The outcome, user, client and at of the approval or rejection, or null.
withdrawal The user, client and at of the withdrawal, or null.
appliedAt, removedAt When it was applied or removed, or null.

propose_source proposes a Postgres database as a source. On an installed server it is refused, with: "This server can't use a Postgres database as a source. Add a web service instead." An agent cannot propose a web service through MCP. It can still list, get and cancel proposals. A person can add a web service in the portal, under Sources.

Input Required What it is
name yes A DNS-style name for the source, such as delivery-metrics.
host yes The database's host.
port no Its port. Default 5432.
database yes The database's name.
consumers no Which of query, orchestrator, bi and catalog use it. Default: all four.
credentials yes A login for each consumer that connects directly: query, orchestrator, bi and catalog, each a username and a passwordRef. A passwordRef is a secret reference, such as vault://kv/sources/ops#password, never the password. A vault:// reference must sit under kv/sources/.
datasets no The schema.table entries to show in BI and wait for in the catalog.
reason no Why the source is needed, up to 2000 characters. The approver sees it.

It's refused if any field holds a secret value, if a source or a live proposal already has that name, or if a reference isn't one a source may use. The result is the proposal plus next, which says who may approve it. Call get_proposal until plan is filled in.

Input Required What it is
name yes The proposal's name.

Returns the proposal: its phase, the plan the approver sees, and who decided what.

Input Required What it is
mine no true lists only proposals you made.
phase no Lists only proposals in this phase.

Returns proposals, newest first.

Input Required What it is
name yes The proposal's name.

Cancels one of your own proposals while it's still pending_approval. Someone else's proposal, or one that's been decided, is refused. An approver withdraws an applied change in the portal.

No inputs. Returns components: for each of the stack's tools, its component, role, adapter and mcp. mcp is null for a tool with no MCP server of its own. Otherwise it gives the url, the protocol revisions, the token audience and clientScope to ask for, the userClaim and identity the tool acts on, how it's audited, and its tools. Read data and metadata through those servers, with a token for their audience. The portal doesn't pass requests on to them.

No inputs. Returns metrics, the metrics you may run with run_metric. Each has its source, name, label, description, owner, kind, format (when declared), mart, the dimensions you can slice and filter by, and guarded.

You see a metric only when its mart has a row-level rule and you're in one of the mart's reader groups. Someone who may run none gets an empty list. When some declared metrics couldn't be read, notServed says so.

Runs a declared metric as you, read-only, and returns its value. You see only the rows you may see.

Input Required What it is
metric yes The metric's name, from list_metrics.
groupBy no Up to 4 columns to slice by.
where no Up to 10 conditions, added to the metric's own.
grain no day, week, month, quarter or year, for the first date column in groupBy.
orderBy no metric, largest value first (the default), or group, by the slice columns.
limit no 1 to 1000 rows. Default 1000.
source no The source that declares the metric. Needed only when two sources declare the same name.

A condition names a column and an operator: equals, notEquals, in, notIn, gt, gte, lt, lte, isNull, notNull, withinLast or olderThan, with a value where the operator takes one. {"anyOf": [...]} joins 2 to 10 conditions with or. Who the query runs as comes from your token only, and any other argument is refused.

Each person may run 30 metric queries a minute, and the server runs 4 at once. A refusal ends with a code in brackets:

Code Means
not-a-reader-or-unknown There's no metric by that name that you may run. A metric that doesn't exist gets the same answer.
ambiguous-metric More than one source declares it. Give source.
rate-limited You've used your 30 a minute. The message says when to try again.
too-large The request is too large. Ask for fewer conditions or values.
busy The server is already running 4. Try again.
failed The query failed.

The audit log keeps the metric's name and the column and operator names, never a condition's value.