The AKCS MCP server — a developer's reference

What is the AKCS MCP server?

A Model Context Protocol endpoint that lets an AI client read and act on a community running on AKCS — the same catalogue, and the same per-user scoping, as the assistant built into the resident app and the admin portal.

It matters because the alternative is screen-scraping or a bespoke integration. With MCP, any compliant client speaks to a community through one documented surface, and the permissions are the ones the person holding the session already has.

How do I connect?

One endpoint, JSON-RPC 2.0:

`` POST https://<your-community>.akcs.io/api/mcp/ Authorization: Bearer <Firebase ID token> Content-Type: application/json ``

Four methods are implemented: initialize, ping, tools/list and tools/call.

Listing the catalogue:

`` {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``

There is no anonymous access and no API key. The bearer token is the same Firebase credential the apps use, so a client acts *as a person* — never as the platform.

What is in the catalogue?

Seventy tools across eleven domains, of which fifty-five read and fifteen write.

What do the tool annotations mean?

Every tool carries the standard MCP annotation block, so a client can reason about a call before making it:

If you are building a client, readOnlyHint is the flag worth respecting: it lets you run a read-only session with no approval UI at all.

Why does a write need a human?

Because an assistant with access to a society's gate and ledger is only safe if something outside the model decides what actually happens.

Write tools are two-phase. The agent loop refuses to execute a tool marked for confirmation until a human has approved that exact call — not the intent, the call, with its arguments as rendered. The approval token is signed, bound to that user and that conversation, and expires in fifteen minutes.

Three further constraints apply regardless of how a client behaves:

1. Ids from the model are never trusted. Every space and user id in a tool's arguments is validated against the caller's own context, so a client cannot reach another community by supplying its id.
2. The catalogue is role-scoped. A resident's tools/list does not contain the admin tools at all — they are absent, not refused. A client cannot call what it never received.
3. Output is whitelisted per tool. Responses are built field by field, never by serialising a model wholesale, so a schema change cannot silently widen what an AI client sees.

Together these mean prompt injection in community data — a complaint description, a visitor's name — has no path to a mutation. There is a live test that plants an instruction-override string inside a complaint and asserts nothing is written.

What errors should a client expect?

Tool failures are typed rather than generic: a tool that does not exist, a permission the caller lacks, arguments that fail validation, and a rate limit. Handle rate_limited with backoff — limits are per user per day and per community per day, and they exist to stop a runaway agent loop costing a committee money.

Read tools that return collections are truncated with an explicit marker rather than silently cut, so a client can tell a short list from a clipped one.

Can I turn it off?

Yes, per community, and it is worth knowing before you build against it. One setting strips all fifteen write tools from the catalogue, leaving a strictly read-only surface. Another disables the assistant and the endpoint entirely. A committee that wants answers without actions can have exactly that, and your client should degrade gracefully when tools/list comes back read-only.

Where next?

See the AKCS AI product page for how the same catalogue is used inside the apps, how to use the assistant and Siri for the resident-facing side, and who can see your data for the wider access model. To discuss an integration, book a demo.