Keen MCP Server

The Keen MCP Server is the door an AI agent uses to configure your organization without a person clicking through the admin console. It speaks the Model Context Protocol — the open standard through which an AI assistant discovers and calls the tools a server offers — over HTTPS and lives at https://<your-host>/mcp — the same host as your admin console. Any MCP client that supports HTTP servers can connect.

What it exposes is the admin surface you already know, as tools — 96 of them, one per admin action, grouped exactly like the console's sections. A tool call is an admin action: it is checked against the calling account's role, refused or applied by the platform, and recorded in the audit trail — exactly as if a person had pressed the button. A handful of read-only resources (your spaces, API keys, contracts, consumers and log settings) are published alongside so a client can browse lists.

The server is for provisioning, not chatting: an agent uses it to create a space, an agent, the API access chain and an end-user identity, and then talks to your agents the way every end user does — over the live chat connection.

An agent signs in as an MCP account — a login for an AI agent, not a person, created once by a human admin under Organization → MCP Accounts. An MCP account has:

• A name — a label, unique across MCP accounts and fixed at creation (up to 100 characters). A typo means delete and re-create.
• A role — the same roles your people have. The role's read and write scopes decide what the agent may do.
• An Enabled switch — off, and the account cannot sign in.
• A credential pair: the account id, always visible on its page, and a secret minted on save and shown once. There is no email and no password.

Hand the agent the id and the secret. The account's page shows when it last signed in (Last login …, or Never used).

Creating, changing the role of, disabling, rotating or deleting an MCP account is a human-only action — it needs the mcp_accounts write scope on a human role. An agent can never do any of that, even if its role would otherwise allow it.

1. Register the server in your MCP client with the URL https://<your-host>/mcp. With Claude Code, for example: claude mcp add --transport http keen https://<your-host>/mcp (client-specific — check your client's own documentation). A project-scoped registration file works the same way: an HTTP server entry with that URL. A newly added server is picked up when the client session (re)starts, not mid-session.
2. Sign in. The agent calls the mcp_login tool with the MCP account's id and secret. On success the tool answers Logged in as MCP account …; on failure Login failed (status 406) — the same refusal whether the id, the secret or the Enabled switch was the problem, so a probe learns nothing.
3. Work. Every other tool now acts as that account. The sign-in token stays inside the MCP session and is never returned to the agent; the session renews it by itself while it is valid, and the logout tool drops it.

tool: mcp_login
args: { "id": "<mcp account id>", "secret": "<the secret shown once in the console>" }

→ "Logged in as MCP account <id>."
// every other tool now acts as this account. The sign-in token stays inside the
// MCP session — it is never returned to the agent — and is renewed by the session.

→ "Login failed (status 406): …"
// the same refusal whether the id, the secret or the Enabled switch was wrong

The session is stateful: a client opens one session and reuses it. A call without a session is refused with Bad Request: no valid MCP session. Send an initialize request first. Each session holds its own sign-in, so two agents on the same endpoint never share an identity.

Organization view

List and inspect MCP accounts — to check one exists before asking a human to create it — but never create, change or delete one.

Spaces

List spaces, inspect one (its agents and its deployment token — the detail read carries the token, the list does not), create, rename or describe, delete (the agents inside cascade), reset the deployment token (the old one dies immediately), and rebuild the spaces cache.

Agents

List a space's agents, inspect, create — display name, slug, Start Flow and Start Node, under the same rules as the console: the slug is lowercase letters and single dashes up to 100 characters; Start Flow and Start Node begin with a capital letter, letters and digits only, up to 60 — rename, re-point the run entry, toggle Active, delete, and read or write both settings channels, JSON Settings and Front Settings, each as one whole JSON document.

API access chain

Api keys: list, inspect, create, rename, bind or unbind the four pieces, rotate (the old secret dies immediately), Wake, delete. Clients: list, inspect, create (an id and a secret are minted; the secret is shown once), rename, rotate, delete. Certificates: list and inspect public material only — the private key never leaves the platform — create (with an optional 16–32 character shared key), update, rotate, delete. Webhooks: list, inspect, create a named Origin + notification URL pair (the Origin is scheme://host[:port], compared exactly), update, delete. Names are up to 100 characters throughout.

Contracts & policy

List, inspect, create, rename or re-key, delete (its consumers are released, not blocked), set the five-toggle registration and login policy (all five toggles every time), and replace the master, default-system and default-outside space sets — up to 200 ids, and the defaults must be subsets of the master set.

Consumers (people)

View only — list, inspect, and the enriched info view. Creating, resetting a password, assigning spaces or a contract, and deleting a human consumer are human-only.

Cache

Read a resource cache's status, rebuild or invalidate one resource, and rebuild only what is bound to one api key — the key, its certificate, client, contract and policy, the contract's spaces and their agents — then Wake the same key so the partner re-reads fresh data.

Logs

The channel switchboard (list, toggle), the audit and file tails, and the per-space, per-agent Log Records — list, reveal a record's read token, create, update, delete.

MCP consumers

The full lifecycle of the agent's own end-user identities, plus minting their tokens — see below.

Every destructive tool — every delete, every rotate, and resetting a deployment token — is flagged as destructive, so a well-behaved client confirms with you before calling it.

• Human accounts — not even reading them. Every account tool (list, inspect, create, assign role, reset password, delete) and the "my account" tools answer 403 MCP accounts may not access this resource for an MCP sign-in.
• Roles — the whole section, read and write.
• MCP accounts — reading is allowed; creating, changing the role, enabling or disabling, rotating the secret and deleting are human-only.
• Human consumers — reading is allowed; every write is human-only.

Why: these walls are a property of being an MCP account, not a scope you can grant or remove — they hold even for an MCP account whose role is admin. An agent must never be able to widen its own permissions, create logins, or manage people or other agents' logins. If a bot reports that it "can't create an account", that is by design — a human does it.

Each tool needs one scope at one level — read or write — from the same catalog roles are built from: the fourteen values on the Roles & Permissions page. Each tool's own description states the scope it requires, and the platform re-checks the account's role on every call — the console's permission rules and the server's are the same rules. A role short of the scope is refused with 403 Forbidden.

Tool descriptions name a scope by a short abbreviation followed by the level — 1 = read, 2 = write — so sp2 means "write on spaces". This is how the abbreviations map to the scope names you grant on a role:

The built-in owner and admin roles pass every scope check — but still hit the four walls above. A full build — space, agent, API access chain, contract, cache and an MCP consumer — needs write on spaces, agents, clients, certificates, webhooks, contracts, api_keys, cache and mcp_consumers (plus read on consumer if the agent looks people up).

A role change is picked up by a running agent session at its next token renewal, and by every new sign-in.

To talk to an agent — to test a flow it just deployed — the agent needs an end-user identity, because the live chat accepts only a signed-in consumer. An MCP consumer is that identity: a consumer with no email, no password and never a one-time passcode; its credential is an id plus a secret.

• Provisioning is MCP-only. Creating an MCP consumer, binding it to a contract, granting it spaces, and minting or refreshing its token are things only an MCP account can do; a human sign-in is refused with 403 Only MCP accounts may manage MCP consumers. The console has no create page for them.
• The lifecycle is shared. In the console under Ai → MCP Consumers, a human with the mcp_consumers write scope can turn a consumer's access on or off, rotate its secret and delete it — never create or re-assign it. The list shows each consumer's contract, enabled state, last login and creation time; the detail page adds its spaces and the MCP account that created it.
• Create with a name (unique and immutable), the contract it belongs to (its tenant), the spaces it may reach (a subset of the contract's master set) and an Enabled flag (on by default). The reply carries the consumer record and its secret — shown once, never retrievable. A consumer with no contract cannot obtain a token; unbinding it wipes its spaces.
• Its token comes only from here. The agent mints the consumer's access + refresh pair from the id and secret — the same pair a human consumer gets after login, without the passcode step — and uses the access token on the partner-facing API and the live chat. A partner site's login never issues one. Refreshing also happens only through the server; a consumer that was disabled, deleted or lost its contract is refused.
• Every token failure is a uniform 406 — unknown id, wrong secret, disabled, no contract or an incompletely bound access chain all look the same.

• The secret is shown once and stored hashed — at creation and after Rotate Secret. Rotating mints a new secret and the old one stops verifying at that instant. Rotation governs future sign-ins; it does not end a session that is already signed in — to cut access, disable.
• Disable to cut access. A disabled account cannot sign in, and a running session is refused at its next token renewal — so access ends shortly after, without deleting anything; turn it back on to let the agent in again. Deleting the account has the same effect and removes the identity for good.
• The sign-in token never leaves the platform side of the MCP session — it is not returned to the agent, and the session renews it itself.
• Every action is audited under the MCP account. A sign-in is recorded, and every action the agent takes lands in the same audit trail as a person's — the requester recorded is the MCP account's id and role. Because an MCP account has no email, the requester's email field is empty on those lines; identify the actor by its id. When an agent creates an MCP consumer, the consumer records which MCP account created it.
• Nothing an agent does can widen its own access — the four walls above hold regardless of role.
• Destructive tools are flagged so the client can ask you first.

Not authenticated

Not authenticated — call the mcp_login tool first — the session holds no sign-in. Call mcp_login with the account id and secret.

Login failed (406)

Wrong id, wrong secret, or the account is disabled — deliberately the same message for all three. Check the credential pair; an admin can see the Enabled switch and rotate the secret.

401 mid-session

The session could not renew its token — the account was disabled or deleted, or the renewal window passed. Sign in again with mcp_login.

403 · Forbidden

The account's role lacks the scope the tool names. An admin extends the role, or assigns another.

403 · human-only

MCP accounts may not access this resource — accounts, roles, MCP-account changes or a human-consumer write. Ask a human admin.

403 · MCP-only

Only MCP accounts may manage MCP consumers — a human sign-in tried to create, assign or mint a token for an MCP consumer; those are MCP-only.

406 · 400 · 404

406 is a refused request: a validation rule, a duplicate name, rebuilding the caches of an api key that is not fully bound (the message names the missing bindings), or — on the consumer-token tools — a uniform refusal that never says which check failed. 400 on Wake for a key that is not fully bound names what is missing. 404 is an unknown id.

503

The platform is temporarily unable to process that request; nothing was applied — retry shortly.

No session

Bad Request: no valid MCP session…, or a refusal naming an unknown or missing session id — your client did not open a session first, or the session has ended. Reconnect the client.