Connect an AI assistant with the MCP server

Point Claude, ChatGPT or your own agent at your Pallara data over the Model Context Protocol — same token, same tenant isolation, same limits, and read-only by design.

Pallara runs a Model Context Protocol server. An assistant connected to it can answer questions about your enrolments, attendance, assessments, finance and cases directly, instead of somebody exporting a spreadsheet first. It authenticates with the same pallara_bulk_ token you mint under Administration → Settings → API access, reads through the same allow-list and row-level security as the REST API, and is read-only — seven tools, all of them reads, with a test that fails the build if a write ever appears in the server.

When MCP is the right choice

Before you start

• You must be a tenant administrator — API access is administrators only.
• You need the staff host for your provider: https://<your-slug>-staff.pallara.app. The tenant comes from the token, not the hostname, but the host is where the endpoint lives.
• No module needs enabling. The MCP server is on wherever the API is.

Set it up

1. Mint a dedicated token. Administration → Settings → API access → Mint a token, named for the assistant — “Claude Desktop (Simon)”, “Ops agent”. One per assistant, so revoking one does not silence the others. It is shown once.
2. Add the endpoint to your client as a Streamable HTTP MCP server: https://<your staff host>/api/mcp, with the token as a bearer credential.
3. Test the connection. Your client should list seven tools. If it lists none, the token or the URL is wrong — see Troubleshooting below.
4. Ask it to list resources. list_resources returns all 51, grouped. This is the cheapest possible proof that the scope resolved to your provider.
5. Ask it a real question. "How many learners are enrolled in the March intake?" — the assistant will find the resource and filter for itself.
6. Review use, and revoke when finished. Every request is against the token; Revoke ends the assistant's access on its next call.

Connecting a specific client

Any client that speaks Streamable HTTP with a bearer credential works. The configuration below is the generic form — a URL and an Authorization header:

{
  "mcpServers": {
    "pallara": {
      "type": "http",
      "url": "https://<your-slug>-staff.pallara.app/api/mcp",
      "headers": {
        "Authorization": "Bearer pallara_bulk_····"
      }
    }
  }
}

Or from a terminal, to prove the endpoint before you configure anything:

curl -s -X POST "https://<your staff host>/api/mcp" \
  -H "Authorization: Bearer $PALLARA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The tools

Seven, and no more. Each one declares itself read-only, non-destructive and idempotent, returns structured output against a published schema, and carries the same JSON as plain text so a client that does not read structured output still works.

find_learner matches an email address or student id on an index, which is exact and always complete. A name has no index — filtering is deliberately restricted to indexed columns, because a LIKE over an unindexed text column is how an API becomes slow — so a name is matched by a bounded scan, and the result carries search_complete. If that is false, narrow the query or search by email or student id instead.

learner_overview returns the twenty most recent enrolments, grades and invoices for display. Its outstanding_balance and open_cases are complete, not a summary of those twenty: the balance counts every invoice the provider can actually collect — never a draft pro-forma, a cancellation, a write-off or something already paid — and open cases are filtered in the query rather than picked out of a recent page.

Questions worth asking it

• "Find the learner Aroha Ngata and show me how she is doing." — find_learner then learner_overview.
• "How many learners are active in the March 2027 intake?" — count_records on enrolments.
• "Which learners have an attendance record below the threshold this month?" — query_resource on attendance_students.
• "What has not been marked in BAIT501?" — query_resource on submissions, filtered on status.
• "What is outstanding across invoices due before the end of the month?" — query_resource on invoices with a dueDate[lte] filter.
• "Which compliance items expire in the next 30 days?" — query_resource on compliance_items.

Limits, stated plainly

What it will not do

• No writes. Seven read tools. There is no write tool, no general write API behind it, and a source-level test fails the build if one appears. An agent that can enrol a learner is a different product decision and must not arrive by accident inside a read integration.
• No other provider. The token resolves to one provider and everything after that runs under row-level security. There is no parameter that widens it, and the hostname does not change it either.
• No confidential learners, and no test records. Same rule as the REST API: a restricted learner is not found, never forbidden.
• No notes written for a narrower audience. A case note scoped to pastoral staff, to its author and managers, or to chosen roles is invisible to a token.
• No MCP Apps, prompts, resources, subscriptions or server-side sessions. Tools only. Every request stands alone, which is what lets it run behind more than one container.
• No batching. One JSON-RPC request per call; a batch array is refused. Both supported protocol revisions removed it.
• Nothing about the shape of your database in an error. A failed read answers “That request could not be completed.” — an error string naming columns is a description of your schema handed to whoever triggered it.

Rotating and revoking

1. Mint the replacement token under Administration → Settings → API access and give it a name that says which assistant it belongs to.
2. Update the assistant's configuration and make one call, so the new token's last used moves.
3. Revoke the old token. It stops working on its next request — there is no grace period and no cached credential.
4. If a token may have been exposed, revoke first and mint second. A short outage is cheaper than an open credential.

Troubleshooting

The full contract, including the exact request and response shapes, is in the API reference.