Skip to content
plugboard.appRequest a demo

Build on it

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.

The same tool catalogue backs Ask in the product, with identical permission checks.

  1. 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.
  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.

Tool
people.search, people.profileFind a pupil or staff member, see their loans, devices and submissions
loans.list, loans.issue, loans.returnThe loan desk
submissions.list, submissions.get, submissions.create, submissions.assignDevice repairs - work lodged against a serial number
tickets.list, tickets.get, tickets.byNumberThe service-desk queue. Read only: nothing here changes a ticket
devices.searchThe asset register
costs.breakdownSpend 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.

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.

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:

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

Check it by hand first:

Terminal
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'

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.

SymptomCause
403 on /api/mcpThe Integrations module is not enabled for this tenant
401Missing or invalid bearer token
413The batch carried more than 32 messages. Split it across requests
429More than 60 requests in a minute from this address
tools/list is emptyThe key has no scopes granting any tool
A tool is missingCheck the key’s permissions and the tool’s required module
Everything 404s including the interfaceWrong hostname. /api/mcp is on your deployment, not on plugboard.app