Skip to main content
Was this helpful?

PrimeCal MCP Tools and Resources

This page documents the canonical PrimeCal MCP surface exposed by the server.

Tool Families​

Organisations, Resources, and Reservations​

  • primecal.organisations.list
  • primecal.organisations.active.set
  • primecal.organisations.billing.status.get
  • primecal.organisations.billing.settings.update
  • primecal.organisations.stripe.onboardingLink.create
  • primecal.organisations.payments.debug.get
  • primecal.resourceTypes.list
  • primecal.resources.list
  • primecal.reservations.availability.list
  • primecal.reservations.list
  • primecal.reservations.get
  • primecal.reservations.create

Common input fields:

  • organisationId for active-organisation switching only
  • resourceTypeId
  • optional resourceId
  • date for day-level availability
  • startTime / endTime for reservation creation
  • optional status, startFrom, and endTo for reservation listing

Important behavior:

  • reservation and resource tools resolve the active organisation from the agent context, not from arbitrary client payloads
  • billing and payment-debug tools also use the active organisation, but require explicit organisation scope and organisation-admin ownership context
  • availability uses the same blocking logic as public booking
  • MCP does not expose Stripe keys, Checkout sessions, payment intents, or webhook handling
  • reservation creation is limited to non-payment flows unless the owner context is acting in an administrative organisation role

Billing-specific input fields:

  • defaultCurrency for billing-safe updates
  • optional reservationId / bookingId
  • optional paymentStatus
  • optional limit

Calendars and Events​

  • primecal.calendars.list
  • primecal.calendars.get
  • primecal.calendars.events.list
  • primecal.calendars.events.create
  • primecal.calendars.events.update
  • primecal.calendars.events.delete
  • primecal.calendar.userGroups.list
  • primecal.calendar.userGroups.details
  • primecal.calendar.userGroups.createInvite
  • primecal.calendar.userGroups.acceptInvite
  • primecal.calendar.userGroups.attachCalendars
  • primecal.calendar.userGroups.detachCalendars

Common input fields:

  • calendarId (number)
  • from / to (ISO 8601 timestamps)
  • eventId or id for updates/deletes
  • event object for create/update payloads

People-group tool input fields:

  • groupId (number)
  • groupIds (number array) for optional filtering on list
  • calendarIds (number array) for attach/detach operations
  • permission (read, write, or admin) for attach operations
  • email and optional message for invite creation
  • token for invite acceptance

People-group tools are gated by calendar.userGroups.* action keys. Attach and detach tools require both group scope and calendar scope.

Tasks and Reminders​

  • primecal.tasks.list
  • primecal.tasks.create
  • primecal.tasks.update
  • primecal.tasks.delete
  • primecal.tasks.labels.list
  • primecal.tasks.labels.create
  • primecal.tasks.labels.update
  • primecal.tasks.labels.delete
  • primecal.reminders.create
  • primecal.reminders.update

Reminder tools are task-backed and map reminder fields (remindAt, note) into task fields (dueDate, body).

Automation​

  • primecal.automation.rules.list
  • primecal.automation.rules.get
  • primecal.automation.rules.trigger
  • primecal.automation.rules.audit.list

Common input fields:

  • ruleId (number)
  • optional status, fromDate, toDate
  • pagination (page, limit)

Profile and Context​

  • primecal.profile.get
  • primecal.context.snapshot

Context snapshot input:

  • days (1-30)
  • tasksLimit (1-200)
  • eventsLimit (1-200)
  • includeCompletedTasks (boolean)

Resources​

  • primecal.current-context (primecal://current-context)
  • primecal.automation-summary (primecal://automation-summary)
  • primecal.calendar.user-groups (primecal://calendar/user-groups)
  • primecal.calendar.user-group-detail (primecal://calendar/user-groups/{id})

Both resources return application/json textual content in MCP resources/read responses.

People-group resources are read-only and only include groups and calendars allowed by the agent's scope.

Enterprise Reservation JSON-RPC Examples​

Switch the active organisation​

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": {
    "name": "primecal.organisations.active.set",
    "arguments": {
      "organisationId": 12
    }
  }
}

Read availability for one service​

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "primecal.reservations.availability.list",
    "arguments": {
      "date": "2026-05-20",
      "resourceTypeId": 8
    }
  }
}

Create a non-payment reservation​

{
  "jsonrpc": "2.0",
  "id": 32,
  "method": "tools/call",
  "params": {
    "name": "primecal.reservations.create",
    "arguments": {
      "resourceTypeId": 8,
      "resourceIds": [41, 42],
      "startTime": "2026-05-20T10:00:00Z",
      "endTime": "2026-05-20T11:00:00Z",
      "notes": "Agent-assisted booking"
    }
  }
}

Read active-organisation billing status​

{
  "jsonrpc": "2.0",
  "id": 33,
  "method": "tools/call",
  "params": {
    "name": "primecal.organisations.billing.status.get",
    "arguments": {}
  }
}

Update the default billing currency​

{
  "jsonrpc": "2.0",
  "id": 34,
  "method": "tools/call",
  "params": {
    "name": "primecal.organisations.billing.settings.update",
    "arguments": {
      "defaultCurrency": "eur"
    }
  }
}

Prepare Stripe onboarding​

{
  "jsonrpc": "2.0",
  "id": 35,
  "method": "tools/call",
  "params": {
    "name": "primecal.organisations.stripe.onboardingLink.create",
    "arguments": {}
  }
}

Inspect payment-debug state​

{
  "jsonrpc": "2.0",
  "id": 36,
  "method": "tools/call",
  "params": {
    "name": "primecal.organisations.payments.debug.get",
    "arguments": {
      "paymentStatus": "pending",
      "limit": 10
    }
  }
}

People-Group JSON-RPC Examples​

List scoped groups and calendars​

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "primecal.calendar.userGroups.list",
    "arguments": {
      "includeCalendars": true
    }
  }
}

Create a group invite​

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "primecal.calendar.userGroups.createInvite",
    "arguments": {
      "groupId": 9,
      "email": "teammate@example.com",
      "message": "Join the shared planning calendars."
    }
  }
}

The result is intentionally generic and does not disclose whether the email maps to an existing PrimeCal user.

Attach a calendar to a group​

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "primecal.calendar.userGroups.attachCalendars",
    "arguments": {
      "groupId": 9,
      "calendarIds": [5],
      "permission": "write"
    }
  }
}

Read the group summary resource​

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "resources/read",
  "params": {
    "uri": "primecal://calendar/user-groups"
  }
}

Schema and Result Model​

All tools are listed through MCP tools/list and publish JSON Schema-compatible inputSchema objects.

Result shape follows MCP conventions:

  • success: content + structuredContent
  • error: isError: true with structured error payload

Example success envelope:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":42,\"title\":\"Project review\"}"
    }
  ],
  "structuredContent": {
    "id": 42,
    "title": "Project review"
  }
}

Example error envelope:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"type\":\"permission_denied\",\"statusCode\":403}}"
    }
  ],
  "structuredContent": {
    "error": {
      "type": "permission_denied",
      "statusCode": 403,
      "message": "Agent does not have access to this tool or scope."
    }
  }
}

Payload Richness Expectations​

PrimeCal tools should return rich data so AI hosts can reason with minimal extra round trips.

  • Event objects include timeline, recurrence, status, color, and metadata.
  • People-group objects include role, minimal member summaries, invite-safe metadata, and simplified calendar references when scoped.
  • Task objects include labels and task-calendar mirror metadata.
  • Automation responses include rule definitions, counters, and audit records.
  • Reservation objects include assigned resources, resource type, quote snapshot, customer payload, status, and payment state.

Quick Protocol Smoke Test​

  1. initialize against /api/mcp
  2. tools/list
  3. resources/list
  4. tools/call with primecal.profile.get
  5. resources/read for primecal://current-context

May.B.Late demo expectation:

  • primecal.calendars.list should include Work, Personal, and Side projects.
  • primecal.calendar.userGroups.list should return only groups allowed by the agent's user-group scope.
  • primecal.organisations.list should return only organisations allowed by the agent profile and underlying owner access.