@kroombase/mcp

An MCP server for KroomBase — connect Claude, Cursor, VS Code or any Model Context Protocol host to your KroomBase backend.

One session token reaches the whole account: every project, each project's API key, its tables and rows, SQL, and file storage.

Setup

Nothing to clone, nothing to build:

npx -y @kroombase/mcp

Your MCP host launches it. Claude Desktop, Claude Code and Cursor all use the same mcpServers shape:

{
  "mcpServers": {
    "kroombase": {
      "command": "npx",
      "args": ["-y", "@kroombase/mcp"],
      "env": {
        "KROOMBASE_SESSION_ID": "YOUR_SESSION_TOKEN"
      }
    }
  }
}

VS Code keeps its map under servers in .vscode/mcp.json:

{
  "servers": {
    "kroombase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kroombase/mcp"],
      "env": { "KROOMBASE_SESSION_ID": "YOUR_SESSION_TOKEN" }
    }
  }
}

Claude Code can register it in one command:

claude mcp add --scope user \
  --env KROOMBASE_SESSION_ID=YOUR_SESSION_TOKEN \
  -- npx -y @kroombase/mcp

Configuration

| Variable | Meaning | |---|---| | KROOMBASE_SESSION_ID | Your session token. Reaches every project, its API key, SQL and storage. This is the one to set. | | KROOMBASE_TOKEN | Older name for the same value. Either is read. | | KROOMBASE_API_KEY | A project API key, as an alternative. Narrows the tool list to that one project's database. | | KROOMBASE_URL | Base URL. Defaults to https://kroombase.kroombox.com. | | KROOMBASE_PROJECT_ID | Optional. Applied to tool calls that take a projectId when the caller omits it. |

A session token wins when both credentials are set, because the wider tool list is what the caller asked for by supplying it.

One variable is a complete configuration. With KROOMBASE_SESSION_ID set and nothing else, the server reaches every project the account owns: the URL already defaults to the hosted instance, and no project id is needed up front. The token answers who you are, not which project — the project-scoped tools take a projectId argument, so the assistant calls list_projects first and asks you to choose. That is the right default: which project an app talks to is your decision, not the config's. KROOMBASE_PROJECT_ID only pre-fills that argument for a single-project setup.

Where the session token comes from

In KroomBase: Settings → Security → Session tokens → Create. Name it, choose a lifetime (1h to 1y). The plaintext is shown once, at creation — copy it then.

Keep it in the environment of the process that runs the MCP server. A session token is the whole account: it does not belong in a repository, a shared config file, or a browser bundle.

Tools

The server is a thin bridge: it forwards each JSON-RPC message to POST /mcp and relays the answer. The tool list therefore comes from the server, not from this package, and cannot go stale when a tool is added.

| Tool | What it does | Credential | |---|---|---| | account_overview | Everything at once: projects, schemas, tables, columns, buckets and API keys. | Session token | | list_projects | Projects this credential reaches, with their ids. Call it first. | Either | | create_project | Create a project (schema, row and API key). | Session token | | delete_project | Drop a project's schema and bucket. Needs its name as confirmation. | Session token | | get_project_api_key | Read a project's REST API key. | Session token | | rotate_project_api_key | Issue a new API key; the old one stops working. | Session token | | list_tables | Every table in one project schema. | Either | | describe_table | Columns, types, keys and foreign keys. | Either | | select_rows | Read rows with one optional filter. | Either | | insert_row | Insert one row, return it. | Either | | update_row | Update one row by integer id. | Either | | delete_row | Delete one row by integer id. | Either | | run_sql | Raw SQL, scoped to one schema, in a transaction. | Session token | | list_buckets | Every bucket: one per project, plus standalone ones. | Session token | | list_objects | Files and folders inside a bucket. | Session token | | upload_file | Write a file into a bucket, creating folders on the way. | Session token | | create_folder | Create a folder inside a bucket. | Session token | | delete_object | Delete a file or folder from a bucket. | Session token | | create_bucket | Create a standalone bucket owned by the account. | Session token | | delete_bucket | Delete a standalone bucket and its files. Needs its name. | Session token | | create_project_bucket | Bring a project's bucket into being. | Session token | | download_file | A file's bytes, base64-encoded, with its sha256. | Session token |

Tools a credential cannot use are never advertised, so an assistant never attempts a call that will be refused. With an API key, only the seven database tools appear.

Licences and limits worth knowing

• Writes are live. There is no draft state and no undo. delete_project and delete_bucket require the resource's name as a confirmation argument for that reason.
• API keys returned by account_overview and get_project_api_key are secrets. They belong in the application's environment, not in source code. Rotating one invalidates the old value immediately.
• download_file returns whole files. It is for reading a file's contents, not for bulk data movement.
• upload_file accepts up to 25 MB per call.

Troubleshooting

| Symptom | Cause | |---|---| | No credential found on startup | Neither KROOMBASE_SESSION_ID nor KROOMBASE_API_KEY is set in the host's config. | | 401 unauthorized | The header never arrived — check the variable name is inside env. | | 401 token_revoked | The token was revoked in Settings, or has expired. Create a new one. | | could not reach | Wrong KROOMBASE_URL, or the host has no network access. | | A tool is missing from the list | You configured an API key; session-only tools are hidden. |

Licence

MIT