passdesk

Connect your AI assistant

Ask about your diary, your learners, and who owes what — in plain English. On every school plan.

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, but it can’t charge or change a record. Reading works on every school plan. On the Scale plan, if you allow it (with an API key where you ticked Let AI assistants book and cancel lessons, or by approving write access on the sign-in screen), it can also book and cancel lessons. Every booking or cancellation shows you a preview first and waits for your go-ahead.

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. The approval covers your school only, and you can disconnect it at any time.

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 only 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. Both are read-only and scoped to your school, like the other tools. Tick Passdesk in the sources list when you start a deep-research run.

Or use an API key (Scale plan). For CLI tools and clients you configure by hand, mint a key in Passdesk under Settings → API keys and send it as a Bearer header. Tick read-only unless you want your assistant to book and cancel lessons; if you do, leave read-only off and tick Let AI assistants book and cancel lessons instead. Full access on its own doesn’t turn the booking tools on. The endpoint uses stateless Streamable HTTP, the current MCP transport.

Claude Code

Claude Code can sign in too, so you don’t need a key: add the server without a header, then run /mcp in Claude Code and choose to authenticate.

claude mcp add --transport http passdesk https://app.passdesk.co.uk/api/v1/mcp

Or, on Scale, with an API key:

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

Thirteen read-only tools, scoped to your school. The last two are the ones ChatGPT deep research calls; other assistants use the eleven above them.

Tool	What it returns
`get_school_overview`	Your school’s name, timezone and headline counts.
`search_students`	Find students by name, email, or phone.
`get_student`	One student in full: licence, theory and practical test, preferences. Date of birth, licence number and guardian details only if you share them.
`get_student_progress`	Skill ratings logged against a student, newest first.
`list_lessons`	Lessons by date range, status, student, or instructor — in your school’s timezone.
`list_instructors`	Instructors with working patterns and ADI badge details.
`list_purchases`	Packages, deposits, and fees — filter by student, status, or date.
`list_products`	Your lesson packages and add-ons, with prices.
`revenue_summary`	What you took between two dates, by month or week if you like — the same figure as your dashboard — plus what’s still owed.
`find_students_without_lessons`	Learners with no lesson in the last so many days and nothing booked.
`lesson_counts`	How many lessons between two dates, by status, for the school or each instructor.
`search`	One search across learners, lessons, instructors, products, and purchases — used by ChatGPT deep research.
`fetch`	Opens one record from a search result in full, with a link back into Passdesk — used by ChatGPT deep research.

With write access

Two more tools appear when the connection has write access (an API key with Let AI assistants book and cancel lessons ticked, or a sign-in where you approved it). Both take two calls: the first returns a preview and changes nothing, and your assistant shows you that preview before making the second call to confirm. A cancellation always sends the learner the usual notice; to cancel without telling them, use Passdesk.

Tool	What it does
`book_lesson`	Book a student into an open slot — previews first, then acts only when confirmed.
`cancel_lesson`	Cancel a lesson — quotes any late-cancellation fee in the preview before acting. The learner is always told.

Agent skills

The agent skills pack gives Claude three workflows that use the tools above:

Weekly review — a Monday summary of 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 Markdown file you can edit.

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. Read-only API keys work here even though MCP requests are POSTs. Write access has to be granted separately, and every write shows a preview and needs confirmation.
Scoped to your school: every query is limited to your school’s data.
No health notes: learners’ health notes never reach your assistant. Their date of birth, provisional licence number and parent or guardian contacts only do if you tick the box for them when you create the key or approve the connection.
Notes are labelled as data: lesson notes, cancellation reasons and other text your learners and staff write come back marked as untrusted, with an instruction that it is information to report, not instructions to follow. That makes it harder for a note written to trick your assistant to work, but it isn’t a guarantee, so keep confirmation prompts switched on for booking and cancelling.
Revocable: revoke the key under API Keys and the connection stops working on the next call.
Rate limited: 300 tool calls per minute per key, with standard RateLimit-* headers. A confirmed booking or cancellation also counts towards the key’s 120 writes a minute, which it shares with the REST API.
Your choice of assistant: whatever your assistant reads is sent to that AI provider under your agreement with them, and you remain the data controller. Connect an assistant your school is comfortable with, and use a read-only key so a leaked key can read data but not change it.

Want the raw API?

The MCP endpoint sits on the same public API the API reference documents, with the same keys and fields. Anything an MCP tool returns, you can also fetch yourself with curl.