Keen Mastering Toolkit

Keen Mastering is the package a building assistant works from. It carries the Keen MCP Server registration the assistant provisions through, the three build tools — keen-validate (check a project), keen-deploy (deploy it) and a runner (prompt the live agent and read the trace) — the platform's guides as context, and three commands that tie them together: /keen-install, /keen-start and /keen-project-validate. Why the assistant works this way, and what it does in the loop, is on the AI-Assisted Building page; this page is the how.

An MCP-capable assistant

Claude Code or another agent that can register an HTTP MCP server, plus Node 18 or newer and a tunnelling tool (the toolkit is built around ngrok) so the platform can reach a partner site running on your machine. Nothing to compile — the two command-line tools ship prebuilt for Linux, macOS and Windows.

Your KeenAgents host

The address you were given. The assistant asks for it first and derives everything else from it — you are never asked to choose a mode or an endpoint.

An MCP account

Created by a human admin under Organization → MCP Accounts, with a role that can write spaces, agents, clients, certificates, webhooks, contracts, api keys, cache and MCP consumers. You give the assistant its id and its once-shown secret.

Names

The space name and the agent's display name — and, if you don't take the defaults, the agent slug, Start Flow and Start Node.

Two folders

Where the flow project should live (it may not exist yet — the assistant scaffolds it) and where your copy of the reference partner site is.

An end-user identity

Either let the assistant create a new MCP consumer, or give it the id and secret of an existing one.

1. Unpack the toolkit and open your assistant in that folder. The folder carries its own registration of the Keen MCP Server; approve the one-time prompt.
2. Run /keen-install — once per machine, always first. It checks the prerequisites and reports their versions, copies the prebuilt keen-validate and keen-deploy for your operating system onto your path, installs the runner, and ends with "Next: run /keen-start". /keen-start refuses to run until this has been done.
3. Run /keen-start — or just say hello: the assistant runs it on its first reply.

Every session starts with a status banner — whether the MCP server is connected, whether the two tools are installed, and how many saved projects exist — followed by one choice:

• Create new project — the wizard below, then the whole 15-step setup, saved as a project.
• List existing projects — pick a saved project; the assistant reconnects, signs in, checks that the space and the api key still exist, and continues where you left off.
• Just connect — no project: sign in as an MCP account for ad-hoc work; nothing is saved.
• Resume the unfinished project — offered when a previous run stopped mid-way; the assistant picks up at the next unanswered question or unfinished step, re-checking that anything already created still exists.

A project is one space: its ids and settings live in one folder of the toolkit, named after the space — a settings file that holds no secrets, and a private configuration file that does.

1. Space name.
2. Description — default: the space name.
3. Agent display name.
4. Agent slug — default: the name in kebab-case (lowercase letters and single dashes).
5. Start Flow — default Project.
6. Start Node — default Main.
7. Your KeenAgents host address.
8. MCP account id.
9. MCP account secret.
10. The flow project folder.
11. The reference-site folder.
12. MCP consumer — create a new one, or use an existing one (then its id and secret).

The assistant never proposes names, paths or ids for the required answers, never pre-fills them from anything on disk, and re-asks on an invalid answer; optional answers show their computed default as one option. It ends with a one-screen summary (no secrets) and Proceed / Change something.

1. Sign in to the MCP server as the MCP account.
2. Create the space — and remember its id and its deployment token.
3. Create the agent in that space. Its slug, Start Flow and Start Node must match the flow deployed later.
4. Create the certificate, the client (secret shown once) and the consumer contract; assign the space to the contract, set its five-toggle policy and the default spaces new outside consumers receive.
5. Create the api key (secret shown once).
6. Configure and start your copy of the reference site, then tunnel it. The site refuses to boot until its configuration is complete, so the client and api-key values go in first. The assistant reads the port the site actually started on and tunnels that port — or, if it cannot run processes itself, gives you the exact commands and asks for the port and the public URL.
7. Create the webhook — the tunnel's public URL as the Origin (compared exactly), and the site's change-notice route as the notification URL.
8. Bind all four — client, certificate, contract, webhook — to the api key. A key with any binding missing is not live.
9. Finish the site's configuration with the real Origin and restart it. A running site never picks up configuration changes without a restart.
10. Rebuild the key's caches, then Wake it. The partner site is handed the certificate and told to re-read fresh data.
11. The MCP consumer — create a new one bound to the contract and the space (a taken name is retried with a suffix), or bind the existing one you named to this project's contract and space and enable it.
12. Mint the consumer's token from its id and secret. A refusal with an existing consumer means the secret is wrong or the consumer is disabled or unbound — the assistant asks again, or offers to rotate.
13. Write the project — the settings file (no secrets) and the private configuration the runner reads: your host, the consumer token and id, the Origin, the space id, the agent slug, the deployment token and the project folder. Then scaffold the flow project if it is empty — the same skeleton the Flow Builder creates, with a first runnable flow: a start node, one Agent node, an end node.
14. Validate, then deploy. keen-validate must report 0 errors before keen-deploy uploads the project; the platform scans it and answers deployed or rejected at once. A failing validation stops here for you to decide.
15. Report and test — a summary of ids (never secrets) and the exact test-prompt command.

The space and its agent; the complete API access chain — certificate, client, contract with policy and spaces, webhook — bound to one fully-bound api key; your reference site running, tunnelled, allow-listed and woken; an MCP consumer with a live token; a scaffolded flow project already deployed; and a saved project the assistant can reopen. Secrets live in exactly one private file.

From here the runner needs exactly two credentials — the consumer's access token for the live chat, and the space's deployment token for deploys. It never uses the client or api-key secrets; those belong to the partner site alone. Every iteration is the same three commands from the project folder: check, deploy, prompt.

Pick a saved project and the assistant runs every check, then prints one pass/fail table with the exact fix for each failure:

Files

The settings file is complete; the private configuration has every required value and matches the saved ids; the flow project has its layout and passes keen-validate with 0 errors; the reference site's configuration carries the same Origin, client and api-key ids.

Platform

The space exists with the saved title; the agent exists, active, with the saved slug and entry; the api key is fully bound to the saved client, certificate, contract and webhook; the contract grants the space; the webhook's Origin and notification URL match; the MCP consumer exists, is enabled, bound to the contract and granted the space.

Credentials

The consumer's secret still mints a token (never printed); a saved token older than the freshly minted one is flagged.

Live

The site answers on its port; the tunnel is up and its public URL still equals the registered Origin; the notification URL is reachable; the api key's caches have been built.

It ends with VALID — N/N checks passed or INVALID — k failing, and — only if something failed — one question: Fix what can be fixed automatically or Just show me. Auto-fixable: rebinding a half-wired key, re-assigning or re-enabling the consumer, rebuild + wake, re-minting the token, rewriting the site's configuration (a restart is required, and said so). Not auto-fixed, reported with the command instead: starting the site or the tunnel, a changed tunnel URL, a deleted space, agent or contract (that is a new project), and a wrong consumer secret (you retype it, or the assistant offers to rotate).

• When the tunnel's public URL changes, the Origin must move in four places together — the webhook entry, the site's configuration (then restart), the project's private configuration, and the consumer token itself, which is re-minted because the Origin is part of it — followed by rebuild + wake. Skipping any one of the four means silent drops or Invalid token.
• When the consumer token expires, the runner cannot refresh it by itself: an MCP consumer's token moves only through the MCP server. The assistant refreshes it — or mints a fresh one from the stored id and secret — and updates the project.
• Change → rebuild → wake. Forgetting the pair is why "I changed it but the site still sees the old thing".
• Origin is exact-match — https://host is not https://host:3000. A wrong Origin is a silent drop, not an error.
• A secret rotated in the console stales the project. If an admin rotates the MCP consumer's secret from the console, the project's stored secret is outdated — existing tokens keep working, but the next re-mint needs the new value. Run /keen-project-validate and re-enter it.
• MCP consumer names are unique and permanent — a duplicate is refused; pick the final name at creation.
• The Flow Builder extension is not part of this toolkit — the assistant builds a flow by writing its files, not by driving the canvas.