Portal MCP tools
On this page
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).
Connecting
Section titled "Connecting"| 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.
Proposal results
Section titled "Proposal results"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
Section titled "propose_source"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.
get_proposal
Section titled "get_proposal"| 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.
list_proposals
Section titled "list_proposals"| 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.
cancel_proposal
Section titled "cancel_proposal"| 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.
list_mcp_endpoints
Section titled "list_mcp_endpoints"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.
list_metrics
Section titled "list_metrics"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.
run_metric
Section titled "run_metric"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.