The MCP server

Plugboard exposes its operations as an MCP server, so an AI client can search people, look up loans, raise submissions and so on through one authenticated endpoint.

POST https://helpdesk.yourschool.org/api/mcp
Authorization: Bearer <api key>

Transport is streamable HTTP with JSON-RPC 2.0, including batches.

The same tool catalogue backs the in-product assistant, with identical permission checks. There is no second implementation to drift out of step.

Turning it on

1. Enable the Integrations module. Like every module it is off until enabled, and the endpoint 404s while it is.
2. Create an API key with only the scopes the client needs.
3. Point the client at /api/mcp with the key as a bearer token.

A discovery GET on the same URL lists the tools the calling key can actually use, which is the quickest way to check a key is wired up correctly.

The tools

Tool
people.search, people.profile	Find a pupil or staff member, see their loans, devices and submissions
loans.list, loans.issue, loans.return	The loan desk
submissions.list, submissions.get, submissions.create, submissions.assign	Tickets and repairs
devices.search	The asset register
costs.breakdown	Spend by type, coverage or period

tools/list is authoritative. It returns only the tools the calling key’s scopes permit, so two keys see two different catalogues.

What it will not do

Every tool runs as the API key, inside that key’s tenant. MCP is not a way around permissions. A key without loan.issue does not see loans.issue in tools/list and cannot call it. The same permission checks the web interface uses run on every invocation. There is no ambient administrator.

Mutating tools are marked readOnly: false, and the in-product assistant requires explicit confirmation before running one. Over MCP the client is responsible for that confirmation, which is worth knowing when you decide what scopes to put on a key. A read-only key cannot surprise you.

Nothing is exempt from the audit log. Actions taken through MCP are recorded like any other, attributed to the API key.

Wiring up a client

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "plugboard": {
      "url": "https://helpdesk.yourschool.org/api/mcp",
      "headers": { "Authorization": "Bearer pb_live_..." }
    }
  }
}

Check it by hand first:

curl -s https://helpdesk.yourschool.org/api/mcp \
  -H "Authorization: Bearer pb_live_..." \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Your data stays yours, with one honest exception

The MCP server hands tool results to whichever client you connect, so that client’s model sees them. If that matters to you, connect a local one.

This is a different trade from the in-product assistant, which runs against a model you host and never sends anything to an external AI service. That guarantee is about the assistant. It cannot extend to a third-party MCP client you have chosen to connect.

Scope API keys accordingly, and prefer read-only keys for anything you have not audited. If your privacy assessment asks, the distinction is stated on the compliance page.

Troubleshooting

Symptom	Cause
404 on /api/mcp	The Integrations module is not enabled for this tenant
401	Missing or invalid bearer token
tools/list is empty	The key has no scopes granting any tool
A tool is missing	Its permission is not on this key. Check the scopes rather than the module
Everything 404s including the interface	Wrong hostname. /api/mcp is on your deployment, not on plugboard.app