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. A batch is capped at 32 messages; a larger one is refused with 413 and nothing in it is executed. Split the work across requests instead — the endpoint accepts 60 requests a minute per source address, which is 1,920 messages a minute and far more than a client driving a desk will ask for.

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 refuses with 403 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 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	Device repairs - work lodged against a serial number
tickets.list, tickets.get, tickets.byNumber	The service-desk queue. Read only: nothing here changes a ticket
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, so consider it when you decide what scopes to put on a key. A read-only key cannot surprise you.

Audit behavior follows the underlying operation. When an operation writes an audit entry, it carries the API key’s identity. MCP does not add a blanket audit entry for every tool call; see API-key audit coverage.

Wiring up a client

Configure your client’s remote HTTP MCP connection with this URL and header. The exact settings format depends on the client; these are the connection values:

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

Check it by hand first:

curl -s https://helpdesk.yourschool.org/api/mcp \
  -H "Authorization: Bearer pk_..." \
  -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 separate decision from the assistant’s own model. Running local inference does not keep MCP results local: the connected client receives the results its key is authorized to request and may send them to its own model provider.

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
403 on /api/mcp	The Integrations module is not enabled for this tenant
401	Missing or invalid bearer token
413	The batch carried more than 32 messages. Split it across requests
429	More than 60 requests in a minute from this address
tools/list is empty	The key has no scopes granting any tool
A tool is missing	Check the key’s permissions and the tool’s required module
Everything 404s including the interface	Wrong hostname. /api/mcp is on your deployment, not on plugboard.app