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/mcpAuthorization: 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.
The same tool catalogue backs Ask in the product, with identical permission checks.
Turning it on
Section titled “Turning it on”- Check the Integrations module is enabled. It is on by default where the plan includes it, but a school can switch it off, and the endpoint refuses with 403 while it is off.
- Create an API key with only the scopes the client needs.
- Point the client at
/api/mcpwith 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
Section titled “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
Section titled “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 Ask in the product 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.
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
Section titled “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'Where tool results go
Section titled “Where tool results go”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 Ask’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
Section titled “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 |