@gonkalabs/blocks-mcp

Model Context Protocol server for Gonka Blocks — lets AI agents (Cursor, Claude Desktop, Continue, Cline, Zed, …) discover blocks, run them, and build & deploy new ones.

$ gonkablocks-mcp --version
0.1.0

What this gets you

Once connected, your agent can:

• Discover — search_blocks, list_blocks, get_block, list_models, get_pricing_snapshot
• Run — start_run, get_run, get_run_events, read_run_file, cancel_run
• Build — scaffold_block, read_local_block, validate_manifest, deploy_block (full pipeline: tar → upload → Docker build → publish), get_build_status, fork_block
• Schedule — schedule_worker, list_workers, update_worker, delete_worker
• Host — start_session / end_session, deploy_service / stop_service
• Compose — get_workflow, set_workflow
• Use models directly — chat_completions (OpenAI-compatible, billed at the live on-chain rate)
• Manage secrets — list_secrets, set_secret, delete_secret (write-only — agents can never read secret values back)

Plus three starter prompts (build_a_block, fix_failing_run, explore_library) and read-only resources (gonkablocks://docs, gonkablocks://block/{author}/{slug}, gonkablocks://run/{runId}, …).

38 tools total. The full list is enumerable via tools/list.

Install

npm install -g @gonkalabs/blocks-mcp

You don't actually have to install it — most MCP clients can run it on demand via npx. See the per-client snippets below.

Requires Node.js 20 or later.

Authentication

The server reads credentials in this order:

1. Environment variables (recommended for client mcp.json files):
   • GONKABLOCKS_API_KEY — a gk-live-… key from gonkablocks connect or the web UI
   • GONKABLOCKS_SERVER — defaults to https://blocks.gonka.gg
   • GONKABLOCKS_USERNAME — for nicer log lines
2. ~/.gonkablocks/config.json — automatically populated when you run gonkablocks connect from the CLI
3. Anonymous — public read-only tools still work (search, list, anonymous runs)

If neither auth source is set, the agent gets a clear error from any tool that needs credentials, with a one-line fix.

Connect from Cursor

Add to ~/.cursor/mcp.json (or your workspace's .cursor/mcp.json):

{
  "mcpServers": {
    "gonkablocks": {
      "command": "npx",
      "args": ["-y", "@gonkalabs/blocks-mcp"]
    }
  }
}

Then in Cursor: Settings → MCP → Refresh. You should see 38 tools appear under gonkablocks. Try one prompt to test:

Use the gonkablocks tools to find a block that translates text and run it on "Привет, мир".

Connect from Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent path on Windows / Linux):

{
  "mcpServers": {
    "gonkablocks": {
      "command": "npx",
      "args": ["-y", "@gonkalabs/blocks-mcp"]
    }
  }
}

Restart Claude Desktop. The hammer icon now shows the gonkablocks tools.

Connect from Continue / Cline / Zed

Same JSON, different file:

| Client | Config file | | --- | --- | | Continue | ~/.continue/config.yaml (under mcpServers) | | Cline | Cline panel → MCP Servers → Add | | Zed | ~/.config/zed/settings.json (under context_servers) |

The command + args are always npx -y @gonkalabs/blocks-mcp.

Pinning a specific API key per client

If you want one key for personal Cursor and a different one for a shared CI agent:

{
  "mcpServers": {
    "gonkablocks": {
      "command": "npx",
      "args": ["-y", "@gonkalabs/blocks-mcp"],
      "env": {
        "GONKABLOCKS_API_KEY": "gk-live-...",
        "GONKABLOCKS_SERVER":  "https://blocks.gonka.gg"
      }
    }
  }
}

The env vars take precedence over ~/.gonkablocks/config.json.

Pinning a specific MCP version

Some teams want every workstation on the same revision:

{
  "mcpServers": {
    "gonkablocks": {
      "command": "npx",
      "args": ["-y", "@gonkalabs/[email protected]"]
    }
  }
}

Local debugging

Run the server through the official MCP inspector:

npm run inspect
# or
npx @modelcontextprotocol/inspector npx @gonkalabs/blocks-mcp

The inspector lets you see every JSON-RPC frame, fire tools manually, and re-load resources without an LLM in the loop.

Permissions model

The MCP server speaks to the same authenticated REST API the Gonka Blocks CLI uses. There are no special privileges — anything an agent does with this server is something the user could have done themselves with the CLI. Specifically:

• The agent cannot read secret values back. set_secret / delete_secret are write-only. list_secrets returns names only.
• The agent cannot spend more than the user's account balance. Every run is metered against the live on-chain price and capped by the per-block pricing.inference_pass_through rules in the manifest.
• Anonymous mode (no API key) still respects the public 10-runs-per- week cap.

If you're handing this MCP server to a less-trusted agent, mint a fresh dedicated key with gonkablocks connect --name "agent-cursor" and put the key in that client's env. Revoke it later with one click in the web UI.

Documentation

• Full guide for setting this up: https://blocks.gonka.gg/guides/mcp
• Platform docs: https://blocks.gonka.gg/docs
• Block reference: https://blocks.gonka.gg/library
• CLI (companion): https://www.npmjs.com/package/@gonkalabs/blocks-cli

License

MIT — see LICENSE.