MCP server

Groveback ships an MCP server that exposes the admin API as tools, so Claude Code, Claude Desktop, Cursor, Codex and other MCP clients can create collections, schemas, policies, roles, functions, users and seed data by conversation.

It talks to a running server over REST and never imports server internals or touches the database directly.

Wiring it up

First create a project API key with the admin scope — in the dashboard under API Keys. It looks like gb_sk_<projectId>.<secret>.

Claude Code:

claude mcp add groveback_<projectSlug> \
  -e GROVEBACK_URL=http://localhost:8080 \
  -e GROVEBACK_API_KEY=gb_sk_proj_abc123.… \
  -- npx -y @groveback/mcp@latest

Claude Desktop, Cursor, Windsurf — add to the client’s mcpServers config:

{
  "mcpServers": {
    "groveback_<projectSlug>": {
      "command": "npx",
      "args": ["-y", "@groveback/mcp@latest"],
      "env": {
        "GROVEBACK_URL": "http://localhost:8080",
        "GROVEBACK_API_KEY": "gb_sk_proj_abc123.…"
      }
    }
  }
}

Environment

Variable	Required	Meaning
GROVEBACK_URL	yes	Base URL of a running server. Trailing slashes stripped.
GROVEBACK_API_KEY	yes	An admin-scoped key. The project id is embedded, so no project header is needed. Must start with gb_sk_.
GROVEBACK_MCP_READONLY	no	1 or true registers only read tools — every mutating tool is skipped entirely.
GROVEBACK_MCP_NO_UPDATE_CHECK	no	1 skips the startup lookup of the latest version on npm (offline machines). The server’s own hint still applies.
GROVEBACK_MCP_FILES_ROOT	no	The folder upload_local_file may read files from (any format — e.g. PDFs for a knowledge base). Default: the folder the server starts in. Files outside it, also via .. or a symlink, are refused.

The transport is stdio, so all diagnostics go to stderr — stdout carries the JSON-RPC stream.

Tip

GROVEBACK_URL can point at a local grove dev server (http://localhost:8099), not just a deployed project. Remember that a local server’s state is ephemeral until grove pull or grove dev --persist writes it into the bundle.

Staying up to date

Your MCP client starts the server once per session, so a release only reaches you after a restart — and a plain npx -y @groveback/mcp may keep a cached old copy. Use npx -y @groveback/mcp@latest (every snippet here does) so npx checks npm on each start.

When your copy is behind, the MCP says so to the model, which relays it to you with the update steps: once in the next tool result and at the top of get_guide. It learns about a newer release two ways — one npm lookup at startup, and the API itself: every call sends x-groveback-mcp: <version>, and a server shipping a newer MCP answers with x-groveback-mcp-latest and a readable x-groveback-mcp-warning. An older MCP keeps working; it just lacks the newest tools and parameters.

Annotations

Read tools carry readOnlyHint. Destructive ones carry destructiveHint and are prefixed ⚠️ DESTRUCTIVE in the description, so a client can prompt for confirmation. Errors come back as structured results (CODE: message) rather than crashing the server, so the model can self-correct.

The guide tool

Tool	Description
get_guide	The Groveback cheatsheet — permission-string format, the policy DSL, the REST data API, auth routes, the SDK, OpenAPI URLs, the trigger union, and the HTTP handler contract. Worth calling before authoring policies, roles or functions.

Collections

Tool	Description
list_collections	List the project’s collection names.
get_collection_schema	A collection’s JSON Schema.
get_collection_policy	A collection’s policy and its source.
list_indexes	The indexes of a collection.
create_collection	Create one, with its JSON Schema (schema, strongly recommended — it validates writes and types the client, OpenAPI, GraphQL and the dashboard forms); then set a policy, since it is deny-by-default.
delete_collection	⚠️ Drop a collection and all its documents.
rename_collection	Rename.
set_collection_schema	Replace the JSON Schema. x-ref declares a relation.
delete_collection_schema	⚠️ Remove the schema — writes stop being validated.
set_collection_policy	Replace the access policy.
delete_collection_policy	⚠️ Remove it — a file default takes over, else fail-closed.
create_index · delete_index	Manage indexes. System indexes like id_1 cannot be dropped.

Documents

Tool	Description
list_documents	List in a collection — the admin view, which ignores the policy. expand embeds x-ref relations as <field>_ref.
get_document	One document by id, with the same expand.
insert_document	Insert, bypassing policy. id is generated if omitted.
update_document	Mode patch (default) or put (full replace).
delete_document	⚠️ Delete by id.

Functions

Tool	Description
list_functions · get_function	Definitions, including custom HTTP endpoints.
get_function_stats	Aggregate runs and errors across all functions.
list_function_versions · get_function_version	Version history and one snapshot’s full code.
get_function_logs	Recent runs — status, duration, console output, errors.
create_function	An event-triggered function (database, auth, storage, cron) as an ESM module.
create_http_endpoint	A custom HTTP endpoint.
update_function	Any subset of trigger, timing, code, flow, enabled, timeoutMs. Bumps the version.
delete_function	⚠️ Delete a function and its logs and versions.
rollback_function	Roll back to an earlier version — non-destructive, applied as a new version.
invoke_function	Run manually with a test payload; returns the run log synchronously.

Roles and users

Tool	Description
list_roles	roleType is "member" or "enduser".
create_role · update_role	End-user roles accept data-plane permissions only. Built-ins cannot be edited.
delete_role	⚠️ Built-in or in-use roles are refused.
list_users · get_user	The project’s end users.
create_user	Password must be at least 8 characters.
update_user	metadata.role assigns an end-user role, which must exist.
set_user_status	Activate, deactivate (recoverable) or block. The latter two revoke sessions immediately.

API keys

Tool	Description
list_api_keys	Metadata only — secrets are never returned.
create_api_key	The full secret is returned once. Scopes: read, write, admin, storage, functions.
revoke_api_key	⚠️ Revoke immediately.
rotate_api_key	⚠️ New secret returned once; the old one is invalidated.

Integrations

Tool	Description
list_integrations	Secrets redacted to { configured }.
list_integration_providers	The catalog: config and secret field specs, plus the ops callable from ctx.integrations.call().
create_integration	resend, telegram or http. Secrets are encrypted at rest and never read back.
update_integration	Omitted secret fields keep the stored value.
test_integration	Mode dry (recommended) validates through the real path but sends nothing.
save_integration_tests · run_integration_tests	Manage and run the saved dry-run cases (max 20).
delete_integration	⚠️ Functions calling it start failing.

Webhooks

Tool	Description
list_webhooks · list_webhook_deliveries	Signing secrets never returned. Deliveries newest first, capped at 50.
create_webhook	The HMAC signing secret is returned once.
update_webhook	Collection, events, url, headers, enabled. The secret is untouched.
test_webhook	Send a signed test delivery now.
rotate_webhook_secret	⚠️ The old secret stops verifying.
delete_webhook	⚠️ Deletes the webhook and its delivery log.

OAuth, usage and config

Tool	Description
get_oauth_config	Per-provider { clientId, enabled, configured } plus the redirect allowlist.
set_oauth_provider	Configure google or github. The secret is never returned.
set_oauth_redirects	Replace the allowed post-login origins.
get_plan_usage	{ plan, limits, usage } — all null when billing is disabled.
export_config	The project’s shape as one versioned JSON document, no secrets.
import_config	Merge-upsert by name — never deletes. dryRun: true returns the plan only.

What is not exposed

There are no control-plane tools: projects, members, token exchange and the connection registry are absent, because an API key cannot reach those routes — they require a control-plane JWT. Manage them in the dashboard or via the control-plane API.