Skip to main content
Was this helpful?

Connecting MCP Hosts

This page shows practical connection patterns for PrimeCal MCP with the May.B.Late demo user, using a manually-generated static agent API key (ag_sk_...).

If your AI assistant instead offers a Connect or Add connector button and supports OAuth, use Connecting via OAuth instead — it reaches the same MCP server without copying a key by hand.

All sample outputs in this page assume you are connected as mayblate.

Connection Modes​

PrimeCal supports both common MCP transport styles:

  • Streamable HTTP to https://<your-primecal>/api/mcp
  • STDIO via the PrimeCal MCP stdio entry script

Use one agent API key per host instance.

PrimeCal Cloud note:

  • Frontend app: https://app.primecal.eu
  • MCP/backend endpoint: https://api.primecal.eu/api/mcp
  • Do not point remote MCP hosts at https://app.primecal.eu/api/mcp; that host serves the SPA shell, not the backend API.
  • If your frontend is hosted on Azure Static Web Apps Free, /api/* cannot be linked through that frontend host. Use the backend host directly until the SWA is upgraded to Standard.

Chrome MCP (HTTP)​

Use this when your Chrome MCP extension/bridge supports remote HTTP MCP servers.

Before generating the host config in PrimeCal, choose the narrowest permission group that fits the host:

  • Minimal for smoke tests and context-only assistants
  • All read-only for browsing calendars, tasks, reservations, and automation state safely
  • Operational read/write only when the host must create or update planning data
  1. Open your Chrome MCP host settings.
  2. Add a server named primecal.
  3. Set endpoint URL to https://<your-primecal>/api/mcp.
  4. Add header Authorization: Agent ag_sk_<token>.
  5. Save and reconnect.
  6. Run tools/list, then call primecal_calendars_list.

Example JSON block used by many Chrome MCP tools:

{
  "name": "primecal",
  "transport": "http",
  "url": "https://primecal.example.com/api/mcp",
  "headers": {
    "Authorization": "Agent ag_sk_your_token_here"
  }
}

If your extension uses a different field name (endpoint, serverUrl, authHeaders), keep the same values but map them to that UI.

PrimeCal may also emit a non-sensitive permissionGroup annotation in its generated config. Treat that as operator-facing metadata only. The host should still rely on the explicit scoped MCP capabilities returned by PrimeCal.

Claude Desktop (STDIO)​

Use this when you want local desktop-hosted MCP with PrimeCal backend access.

Prerequisites:

  • PrimeCal backend dependencies installed
  • backend built (npm --prefix backend-nestjs run build)
  • valid PRIMECAL_MCP_AGENT_KEY

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "primecal": {
      "command": "node",
      "args": [
        "/absolute/path/to/primecal_app1/backend-nestjs/dist/src/mcp-server/bin/primecal-mcp-stdio.js"
      ],
      "env": {
        "PRIMECAL_MCP_AGENT_KEY": "ag_sk_your_token_here",
        "DATABASE_URL": "postgres://...",
        "JWT_SECRET": "..."
      }
    }
  }
}

Development alternative (without build):

{
  "mcpServers": {
    "primecal": {
      "command": "npx",
      "args": [
        "ts-node",
        "-r",
        "tsconfig-paths/register",
        "src/mcp-server/bin/primecal-mcp-stdio.ts"
      ],
      "cwd": "/absolute/path/to/primecal_app1/backend-nestjs",
      "env": {
        "PRIMECAL_MCP_AGENT_KEY": "ag_sk_your_token_here"
      }
    }
  }
}

VS Code or Cursor​

Most VS Code/Cursor MCP integrations also accept HTTP MCP server definitions.

Use the same values as Chrome:

  • URL: https://<your-primecal>/api/mcp
  • Auth header: Authorization: Agent ag_sk_<token>

Claude Code uses the same remote HTTP transport shape:

{
  "primecal": {
    "type": "http",
    "url": "https://api.primecal.eu/api/mcp",
    "headers": {
      "Authorization": "Agent ag_sk_your_token_here"
    }
  }
}

Start validation with:

  1. tools/list
  2. primecal_profile_get
  3. primecal_context_snapshot

Validation Checklist (May.B.Late)​

After connecting, verify:

  • primecal_profile_get returns timezone: Europe/Budapest.
  • primecal_calendars_list includes Work, Personal, Side projects.
  • primecal_tasks_list returns seeded tasks.
  • tools/list matches the permission group you selected. For example, an All read-only host should not see create, update, delete, or trigger-only tools.

Screenshot Capture​

For repeatable screenshots (agent UI, Chrome host config, tool call output, profile page), use:

In this repository state, PrimeCal UI screenshots are already bundled under docs/assets/agents/. Chrome-host specific screenshots are documented with exact capture steps and target file names in the runbook.