MCP Server Architecture

PrimeCal exposes a standards-compliant MCP server as a first-class integration surface for AI hosts.

• Streamable HTTP transport: /api/mcp

Hosted PrimeCal Cloud deployments expose the MCP endpoint on https://api.primecal.eu/api/mcp. The app.primecal.eu frontend host should not be used as the remote MCP origin. On Azure Static Web Apps, forwarding /api/* from that frontend host to the backend requires the Standard SKU. PrimeCal leaves MCP browser-origin enforcement opt-in through MCP_ALLOWED_ORIGINS so server-to-server hosts can connect without an Origin header.

Always-On Availability Model

PrimeCal MCP is always available when deployed and configured.

• No MCP feature flag controls activation.
• Runtime controls are:
  • MCP process/endpoint availability
  • agent API key validity
  • agent permission scope

Authentication and Permissions

MCP requests are authenticated by an agent API key guard.

Accepted credential formats:

• x-agent-key: ag_sk_...
• x-agent-token: ag_sk_...
• Authorization: Agent ag_sk_...

Permission evaluation path:

1. API key → agent profile
2. agent profile → action permissions and scoped resources
3. owner identity + agent scopes → effective authorization

Agents cannot exceed the owner account's capability boundaries.

Error Mapping

PrimeCal maps backend errors into MCP-consumable envelopes.

• Validation failures → type: "validation_error" (HTTP 400)
• Unauthenticated → type: "unauthorized" (HTTP 401)
• Insufficient scope → type: "forbidden" (HTTP 403)
• Missing resource → type: "not_found" (HTTP 404)
• State conflicts (e.g. booking overlap) → type: "conflict" (HTTP 409)
• Rate limit exceeded → type: "rate_limited" (HTTP 429), retriable: true
• Server/upstream failures → type: "http_error" (5xx), retriable when transient
• Unexpected errors → type: "internal_error"

All error payloads set isError: true, include a human-readable message in content[0].text, and always populate structuredContent.error with { type, message, statusCode, retriable }.

See PrimeCal MCP Tools and Resources for the full error envelope shape and type table.