Agent API

AI Agents and MCP

Manage agent profiles and call the standards-compliant PrimeCal MCP runtime

PrimeCal separates agent management from runtime tool execution. Use /api/agents for CRUD, permissions, and keys. Use MCP JSON-RPC over /api/mcp for tool and resource calls.

JWT for managementAgent key for MCP runtimeScope-aware permissionsMCP standard surface

Availability Policy

PrimeCal MCP is always available when the backend/MCP process is running with valid configuration.

• No feature flag is used for MCP activation.
• Safety is enforced by agent profile scopes and API keys.
• MCP spec reference: modelcontextprotocol.io/docs/getting-started/intro

Source

• Agent management: backend-nestjs/src/agents/agents.controller.ts
• Agent auth guard: backend-nestjs/src/agents/guards/agent-api-key.guard.ts
• MCP HTTP controller: backend-nestjs/src/mcp-server/mcp-http.controller.ts
• MCP session service: backend-nestjs/src/mcp-server/mcp-http-session.service.ts
• Tool/resource registries: backend-nestjs/src/mcp-server/mcp-tool-registry.service.ts, backend-nestjs/src/mcp-server/mcp-resource-registry.service.ts
• Action catalog: backend-nestjs/src/agents/agent-actions.registry.ts

Authentication and Permissions

Surface	Auth model	Notes
/api/agents/*	JWT or user API key	Current user manages their own agents
/api/mcp	Agent key	MCP runtime requires agent credentials

Accepted agent-key headers:

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

Authorization: Bearer ... is not accepted for MCP runtime calls.

Endpoint Reference

Agent Management

Method	Path	Purpose
GET	/api/agents	List current-user agents
POST	/api/agents	Create an agent
GET	/api/agents/catalog	Get action catalog and scoping resources
GET	/api/agents/:id	Get one agent
PUT	/api/agents/:id	Update name, description, or status
DELETE	/api/agents/:id	Disable an agent
PUT	/api/agents/:id/permissions	Replace permission set
GET	/api/agents/:id/keys	List keys
POST	/api/agents/:id/keys	Create key
DELETE	/api/agents/:id/keys/:keyId	Revoke key

MCP Runtime (Canonical)

/api/mcp handles MCP JSON-RPC requests over streamable HTTP.

• POST initialize and method calls
• GET/DELETE for MCP transport/session operations
• session header: mcp-session-id

Legacy Compatibility Surface (Deprecated)

Older custom gateway routes may still exist for migration compatibility in some deployments:

• /api/mcp/metadata
• /api/mcp/actions
• /api/mcp/execute
• /api/mcp/stream

Treat these as transitional and do not use them for new integrations.

Request Shapes

Agent DTOs

• CreateAgentDto: name, optional description
• UpdateAgentDto: optional name, description, status
• UpdateAgentPermissionsDto.permissions[]: actionKey, optional scope
• CreateAgentKeyDto.label: key label

MCP Protocol Basics

1. Send initialize request to /api/mcp.
2. Read mcp-session-id response header.
3. Send notifications/initialized.
4. Call tools/list, resources/list, tools/call, resources/read with mcp-session-id.

People-group action keys

The agent catalog exposes these scoped people-group actions:

Action key	Risk	Scope notes
calendar.userGroups.list	read	Requires explicit user-group scope.
calendar.userGroups.details	read	Requires explicit user-group scope.
calendar.userGroups.createInvite	write	Requires explicit user-group scope and returns privacy-preserving invite output.
calendar.userGroups.acceptInvite	write	Requires explicit user-group scope for invite acceptance.
calendar.userGroups.attachCalendars	write	Requires explicit user-group scope and calendar scope.
calendar.userGroups.detachCalendars	write	Requires explicit user-group scope and calendar scope.

Scopes are intentionally narrow. An agent cannot operate on groups or calendars outside the selected owner-approved scope, and it cannot exceed the owner user's own rights.

Example Calls

Create an agent

curl -X POST "$PRIMECAL_API/api/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May.B.Late Chrome MCP",
    "description": "Daily planning assistant for Chrome MCP"
  }'

Replace permissions

curl -X PUT "$PRIMECAL_API/api/agents/9/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      { "actionKey": "calendar.list", "scope": { "calendarIds": [5, 7, 8] } },
      { "actionKey": "calendar.events.read", "scope": { "calendarIds": [5, 7, 8] } },
      { "actionKey": "calendar.userGroups.list", "scope": { "groupIds": [9] } },
      { "actionKey": "calendar.userGroups.attachCalendars", "scope": { "groupIds": [9], "calendarIds": [5] } },
      { "actionKey": "tasks.list" },
      { "actionKey": "tasks.create" },
      { "actionKey": "user.profile.read" }
    ]
  }'

Initialize MCP session

curl -i -X POST "$PRIMECAL_API/api/mcp" \
  -H "Authorization: Agent $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-05",
      "capabilities": {},
      "clientInfo": { "name": "primecal-docs-example", "version": "1.0.0" }
    }
  }'

List tools (after initialize)

curl -X POST "$PRIMECAL_API/api/mcp" \
  -H "Authorization: Agent $AGENT_KEY" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Best Practices

• Keep agent scopes narrow and host-specific.
• Rotate keys on host migration or suspected leakage.
• Validate with primecal.profile.get before write operations.
• Use MCP tools/list as the source of truth for available capabilities.