Connect your AI assistant

What this is

Passdesk speaks MCP — the Model Context Protocol, the open standard AI assistants use to work with your tools. Connect once and your assistant can look things up for you: “who hasn’t booked in three weeks?”, “which instructors have gaps on Thursday?”, “draft a friendly reminder for everyone with an unpaid balance”. One endpoint works with Claude, ChatGPT, Codex, Cursor, Gemini CLI, and anything else that speaks MCP.

By default everything is read-only. Your assistant can look, summarise, and draft — it can’t charge or change a record. If you choose to allow it (a full-access API key, or approving write access on the sign-in screen), it can also book and cancel lessons — and even then, every booking or cancellation shows you a preview and waits for your go-ahead first. You stay the one pressing the buttons.

Getting connected

There are two ways in, and both point at the same endpoint:

https://app.passdesk.co.uk/api/v1/mcp

Sign in with Passdesk (easiest). Hosted assistants — Claude on the web and desktop, ChatGPT connectors, and any client that supports MCP OAuth — need no key at all. Add the URL above as a custom connector, and your assistant sends you to Passdesk to sign in and approve read-only access. You can disconnect it any time, and the approval only ever covers your own school.

Claude (web and desktop)

Settings → Connectors → Add custom connector, paste the URL above, then sign in as the school owner when Claude sends you to Passdesk.

ChatGPT

Settings → Connectors → Create (needs a plan with connector support), paste the URL above, and pick OAuth when asked how to authenticate.

ChatGPT’s deep research mode works a little differently: it only ever calls two tools, named search and fetch. Passdesk publishes both. search looks across your learners, lessons, instructors, products, and purchases in one go and hands back a shortlist; fetch opens any one of those in full, with a link back into Passdesk so you can check the source. Same read-only, same school-only scoping as everything else here — nothing extra is exposed to make deep research work. Tick Passdesk in the sources list when you start a deep-research run.

Or use an API key. For CLI tools and clients you configure by hand, mint a key in Passdesk under Your school → API Keys — tick read-only; the MCP surface never needs more — and send it as a Bearer header. The endpoint is stateless Streamable HTTP — the current MCP transport — so any up-to-date client can use it.

Claude Code

claude mcp add --transport http passdesk https://app.passdesk.co.uk/api/v1/mcp \
  --header "Authorization: Bearer pdsk_live_<prefix>_<secret>"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "passdesk": {
      "url": "https://app.passdesk.co.uk/api/v1/mcp",
      "headers": { "Authorization": "Bearer pdsk_live_<prefix>_<secret>" }
    }
  }
}

Claude Desktop, Gemini CLI, and other desktop clients

Clients that only launch local MCP servers can reach us through the mcp-remote bridge (needs Node installed):

{
  "mcpServers": {
    "passdesk": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.passdesk.co.uk/api/v1/mcp",
               "--header", "Authorization: Bearer pdsk_live_<prefix>_<secret>"]
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.passdesk]
command = "npx"
args = ["-y", "mcp-remote", "https://app.passdesk.co.uk/api/v1/mcp",
        "--header", "Authorization: Bearer pdsk_live_<prefix>_<secret>"]

Some desktop clients split arguments on spaces — if the connection won’t open, put the header value in an environment variable and pass "Authorization:${PASSDESK_AUTH}" instead.

What your assistant can see

Ten read-only tools, scoped to your school and nobody else’s. The last two are the pair ChatGPT deep research calls; every other assistant uses the named ones above them.

With write access

Two more tools appear when the connection has write access (a full-access API key, or a sign-in where you approved it). Both are two-step: the first call is a preview with no side effects, and nothing happens until your assistant confirms — after showing you.

Agent skills

Tools are the verbs; skills are the playbooks. The agent skills pack teaches Claude three ready-made workflows that use the tools above:

• Weekly review — a Monday-morning brief: last week’s lessons, cancellations and no-shows, and what’s booked for the week ahead.
• Balance chase — finds unpaid purchases, groups them by student, and drafts a polite reminder for each.
• Diary gaps — spots open slots and instructors with light weeks, and suggests learners to offer them to.

Unzip and add them via Settings → Skills at claude.ai, or drop the folders into .claude/skills/ for Claude Code. Each skill is a plain markdown file — open it, tweak the wording, make it yours.

Security and your data

• Read-only by default: with a read-only key (or a sign-in without write access) no tool can create, change, or delete anything — and read-only API keys work here even though MCP travels over POST. Write access is a separate, explicit choice, and every write shows a preview and needs confirmation.
• Scoped to your school: a key sees your tenant’s data and nothing else, enforced on every query.
• Revocable: revoke the key under API Keys and the connection is dead on the next call.
• Rate limited: 300 tool calls per minute per key, with standard RateLimit-* headers.
• Your choice of assistant: whatever your assistant reads ends up with that AI provider under your agreement with them — you stay the data controller. Connect the assistant your school is comfortable with, and use a read-only key so the blast radius of a leaked key is a read, never a change.

Want the raw API?

The MCP endpoint sits on the same public API the API reference documents — same key, same fields, same rate-limit posture. Anything an MCP tool returns, you can also fetch yourself with curl.