MCP Server

What is it?

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and services. The Koolbase MCP server exposes your backend as a set of tools an assistant can call — so instead of clicking through the dashboard or writing CLI commands, you can ask your assistant to do it.

It ships inside the Koolbase CLI. If you have the CLI, you already have the MCP server — no separate install. It runs locally over stdio and talks to the same Koolbase API the dashboard and CLI use, so every operation is subject to the same authorization and limits.

Because MCP is an open standard, the server is not tied to any one assistant. Any MCP-capable client can drive it — Claude Desktop, Cursor, other editors and agents, or your own client that speaks the protocol over stdio. The guide below uses Claude Desktop as the worked example; the same server entry works anywhere, only the config location differs.

Authentication & scopes

The MCP server authenticates with an organization API key (kb_live_…), provided via the KOOLBASE_API_KEY environment variable. The key is required: koolbase mcp serve deliberately refuses to fall back to your CLI login session, so a misconfigured client fails visibly at startup instead of silently acting as your logged-in user account.

Every key has a scope, and the scope is the hard ceiling on what any tool can do — enforced by the Koolbase API, not just the MCP layer:

For an assistant that only needs to look around, give it a read key. Grant write only when you want it changing flags or config. If a tool needs more scope than the key has, it tells you exactly which scope is required rather than failing opaquely.

Setup

First mint a key for the assistant — koolbase login then koolbase keys create --name claude --scope write (or --scope read for a look-but-don’t-touch assistant). The command prints the key once, along with a ready-to-paste MCP config.

Claude Desktop, one command: run koolbase mcp install --key kb_live_… — it writes the config entry for you (preserving any existing servers and backing up the old file), then fully quit and reopen Claude Desktop. Add --codepush-mutations to also enable the code-push publish/recall tools (admin key required). Skip to the confirmation step below.

Manual, or other MCP clients: point any client at the koolbase mcp serve command. Use the absolute path to the binary (which koolbase to find it) — MCP clients spawn the server with their own environment and don’t inherit your shell’s PATH. For Claude Desktop, add this to your MCP config:

{
"mcpServers": {
  "koolbase": {
    "command": "/usr/local/bin/koolbase",
    "args": ["mcp", "serve"],
    "env": {
      "KOOLBASE_API_KEY": "kb_live_your_key_here"
    }
  }
}
            }

Then restart your client fully — on macOS that means quitting with ⌘Q, not just closing the window; MCP configuration is only read at startup. The Koolbase tools become available, and you can ask your assistant something like “what projects do I have on Koolbase?” to confirm the connection.

Whatever the client, the server is the same three things: a command (absolute path to the koolbase binary), the args ["mcp", "serve"], and a KOOLBASE_API_KEY environment variable.

Available tools

The minimum key scope each tool requires is shown alongside it.

koolbase_describe_project and koolbase_get_collection require a write key because they read the same project-export route the snapshot tooling uses. They never return secrets or function source.

Building with your agent

The schema tools exist so a coding agent can generate code that is correctly wired to your backend instead of guessing at it. koolbase_describe_project tells the agent what exists — every collection, its access rules as structured data, its unique constraints, your buckets and deployed functions. koolbase_sdk_conventions tells it how to call it — the real SDK surface for Flutter, React Native or the browser, so a generated query uses the methods that actually exist.

Access rules come back as data, one per verb. Each rule has a kind:

The intended flow: the agent calls koolbase_describe_project once to learn the project (or koolbase_get_collection for one screen’s worth), calls koolbase_sdk_conventions for the platform it’s generating, then writes code — real collection names, rule-respecting queries, the SDK’s actual call shapes.

This works for Flutter, React Native and the web alike: the two SDKs share the same semantics (the same access rules, offline write contract, and cache-then-refresh queries) but have different call shapes — koolbase_sdk_conventions returns the right dialect for whichever one you ask for (flutter or react_native), so a Flutter query builder never leaks into TypeScript and an options object never leaks into Dart.

Example

A conversation with an assistant connected to Koolbase might go:

Behind the scenes the assistant called koolbase_list_flags to read the state, then koolbase_set_flag to change it — each authorized against your key’s scope.

Or, with a coding agent:

The agent called koolbase_get_collection to learn the collection’s access rule, then koolbase_sdk_conventions for the Flutter call shapes — and generated code against your real backend, not a guessed one.

Security notes

• •Scopes are enforced server-side. The MCP server cannot exceed its key’s scope, regardless of what a tool or assistant attempts.
• •Keys cannot mint other keys. A leaked key is bounded by its own scope and cannot escalate.
• •Give assistants the least scope they need. Use a read key for exploration; reserve write for when changes are intended.
• •Your MCP client stores the key in its config file in plaintext. Treat that file as a secret, and prefer a dedicated key per machine so revocation is surgical.
• •Revoke a key at any time from the dashboard. Revocation takes effect immediately.