Skip to main content
Was this helpful?

MCP Server Architecture

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

  • Streamable HTTP transport: /api/mcp
  • STDIO bootstrap: backend-nestjs/src/mcp-server/bin/primecal-mcp-stdio.ts

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

Module Layout​

  • mcp-server/mcp-http.controller.ts: HTTP ingress for MCP JSON-RPC.
  • mcp-server/mcp-http-session.service.ts: MCP session lifecycle and streamable transport wiring.
  • mcp-server/mcp-server.factory.ts: server metadata and registry composition.
  • mcp-server/mcp-tool-registry.service.ts: tool registration and JSON schemas.
  • mcp-server/mcp-resource-registry.service.ts: resource registration.
  • mcp-server/mcp-error.util.ts: backend error -> MCP error mapping.

Domain behavior is delegated to existing backend lego blocks through AgentMcpService and existing domain services (calendars, events, tasks, automation, users, and user groups).

Authentication and Permissions​

MCP requests are authenticated by AgentApiKeyGuard.

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: structured invalid-argument errors.
  • Permission denials: explicit permission errors.
  • Not found: resource-not-found semantics.
  • Runtime failures: consistent internal error shape with retriable hints where possible.

Adding a New Tool​

  1. Add an action key and metadata in agent-actions.registry.ts.
  2. Implement domain behavior in AgentMcpService by reusing existing services.
  3. Register the MCP tool in mcp-tool-registry.service.ts with zod input schema and clear AI-facing description.
  4. Add unit + integration tests for permission checks, shape, and payload quality.

People-group sharing tools follow the same path. Their action keys live under calendar.userGroups.*, and write tools require explicit group scopes; attach/detach tools also require calendar scopes.

Adding a New Resource​

  1. Add read permission key for the resource use case.
  2. Register in mcp-resource-registry.service.ts with stable URI and application/json mime type.
  3. Return compact but context-rich data.
  4. Add resource listing and resource read protocol tests.

Browser MCP Validation Protocol​

For AI-driven end-to-end verification against UI behavior, use the project protocol in:

Demo User for Docs and Screenshots​

PrimeCal seeds a canonical MCP demo user:

  • username: mayblate
  • password: password123
  • timezone: Europe/Budapest
  • calendars: Work, Personal, Side projects

Seed command:

npm --prefix backend-nestjs run seed