Guide · Model Context Protocol

Connect through MCP.

MCP makes Aurelia’s digital infrastructure composable. An authenticated AI client receives governed company context and tenant-isolated decision tools without depending on a dashboard or rebuilding business logic for every model.

What is available

The Streamable HTTP endpoint is POST /api/mcp on your Aurelia deployment. It implements MCP protocol version 2025-03-26 and supports initialize, ping, tools/list, and tools/call.

Every tool call resolves the signed-in user’s current workspace on the server. A client cannot supply or switch a tenant ID in its arguments.

Authentication

The endpoint supports OAuth 2.1 authorization-code flow with PKCE for remote MCP clients. Sign in to Aurelia, approve the read-only scope for the workspace you want the client to read, then let the client exchange the code for its bearer token. The account must be email-verified.

Do not copy Aurelia’s HTTP-only session cookie into an MCP client. Remote clients must use OAuth discovery and PKCE; the server only grants the mcp:read scope and tokens expire after one hour.

Connect and discover tools

1
Connect
Add the deployment’s /api/mcp URL in an OAuth-capable MCP client. The client discovers Aurelia’s OAuth endpoints automatically.
2
Sign in and approve
Aurelia opens a browser session so you can sign in and approve read-only workspace access.
3
Initialise the connection
Send an MCP initialize request to /api/mcp from the authenticated origin.
4
Discover capabilities
Send tools/list. Use the returned input schemas rather than assuming arguments.
5
Call a tool
Send tools/call. Results arrive as JSON serialised in an MCP text-content block.

const response = await fetch("/api/mcp", {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
    "Mcp-Protocol-Version": "2025-03-26"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {}
  })
});

console.log(await response.json());

Available tools

Tool	Use it for
`get_kpi_summary`	Revenue, contribution margin, orders, CAC, media spend, MER and period-level incremental performance.
`get_channel_performance`	Reported versus incremental return by channel, including spend and funnel position.
`get_attribution_comparison`	Finding where last-click attribution over- or under-credits a channel versus the MMM.
`get_metric_definition`	The workspace-approved definition, formula, parameters, owner and lineage for a governed metric.
`reconcile_revenue`	Explaining why store, ad-platform and modelled incremental revenue disagree.
`get_metric_evidence`	Values with their calculation, source lineage, freshness and governing contract version.
`recommend_budget_reallocation`	A guardrailed, budget-neutral recommendation ranked by incremental return.

Call a recommendation tool

This example asks Aurelia to consider moving at most 15% of a channel’s current spend. The recommendation holds total paid budget flat and returns its modelling caveat with the channel moves.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "recommend_budget_reallocation",
    "arguments": { "maxShiftPct": 0.15 }
  }
}

Safety boundary

Read-only transport. MCP cannot create, approve, execute or roll back a budget action.
No raw marts. Tools read through Aurelia’s typed semantic layer and governed metric contracts.
Tenant isolation. Workspace identity comes from the verified server session, never model-provided input.
Honest modelling. Period-level MMM values and directional estimates retain their scope and caveats.
Rate limited. Authenticated tool calls are limited to 60 per user per hour during private beta.

Budget proposals remain inside Actions, where Aurelia records evidence, review and outcomes in the decision ledger.

Errors

Code	Meaning
`-32700`	The request body is not valid JSON.
`-32600`	The JSON-RPC envelope is invalid.
`-32601`	The requested MCP method is not supported.
`-32602`	The tool name or arguments are invalid.
`-32001`	The Aurelia session is missing, expired or not email-verified.
`-32029`	The private-beta tool-call limit has been reached.

Govern workspace access