Connect AI agents (MCP)

What you'll wire up

Gonka Blocks ships an MCP server that exposes the full platform as agent-callable tools. Once it's plugged into your client, the agent can:

Discover — search published blocks, list models, quote live on-chain pricing.
Run — kick off a block, stream events, read outputs, cancel.
Build & deploy — scaffold a new block on disk, validate the manifest, run the full tar→upload→Docker-build→publish pipeline, watch progress live.
Schedule, host, compose — workers (cron), sessions (per-user containers), services (shared HTTP), workflows (DAGs of blocks).
Use models directly — OpenAI-compatible chat_completions, free for now while Gonka Labs sponsors the platform.
Manage secrets — write-only; list_secrets returns names, never values.

Total: 38 tools, 5 resources, 3 starter prompts. The complete surface area is enumerable via tools/list.

Install the MCP server

You don't actually have to install anything globally — most clients can run the server on demand via npx. But if you want it installed:

npm install -g @gonkalabs/blocks-mcp

Verify:

gonkablocks-mcp --version
# 0.1.0

Requires Node.js 20 or later. Same prerequisite as the CLI.

Connect your account

Easiest path: install the CLI and run gonkablocks connect once. That writes ~/.gonkablocks/config.json with a long-lived API key, which the MCP server picks up automatically.

Or, set environment variables in the client's MCP config (see per-client snippets below) — those take precedence:

GONKABLOCKS_API_KEY=gk-live-...
GONKABLOCKS_SERVER=https://blocks.gonka.gg
GONKABLOCKS_USERNAME=you  # optional, just for prettier logs

If neither auth source is set, the server still starts in anonymous mode — public read-only tools (search_blocks, list_blocks, list_models) work, and so do anonymous runs (10 per week).

Cursor

Edit ~/.cursor/mcp.json (create if missing), or use a per-workspace .cursor/mcp.json:

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

Open Settings → MCP in Cursor, hit Refresh. You should see 38 tools under gonkablocks. Test it:

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

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform. Same JSON as Cursor:

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

Restart Claude Desktop. The hammer icon will show the tools.

Continue, Cline, Zed

Same command + args, different config file:

Continue — ~/.continue/config.yaml under mcpServers:
Cline — Cline panel → MCP Servers → Add
Zed — ~/.config/zed/settings.json under context_servers

Tools your agent gets

The full table lives in the package README. Here's the high-level grouping so you know what to ask for:

Group	Tools
Identity	`whoami`, `list_api_keys`, `mint_api_key`
Blocks	`search_blocks`, `list_blocks`, `get_block`, `get_block_source`, `fork_block`
Models & pricing	`list_models`, `get_pricing_snapshot`
Runs	`start_run`, `get_run`, `get_run_events`, `read_run_file`, `list_run_files`, `list_my_runs`, `cancel_run`
Build & deploy	`scaffold_block`, `read_local_block`, `validate_manifest`, `deploy_block`, `get_build_status`
Sessions / Services / Workers / Workflows	full CRUD per group — see README
Inference	`chat_completions` (OpenAI-compatible)
Secrets	`list_secrets`, `set_secret`, `delete_secret` (write-only — values are never returned)

Starter prompts

The server registers three reusable MCP prompts you can invoke from your client's prompt picker:

build_a_block — given a one-line description of what the block should do, the agent scaffolds, deploys, and tests it end-to-end.
fix_failing_run — point the agent at a failed run and it reads the events log, identifies the root cause, and proposes a fix.
explore_library — describe a topic, get back the three best published blocks for it.

Permissions & safety

The MCP server is just a thin wrapper over the same authenticated REST API the CLI uses. The agent can do anything you can do — and nothing more. Specifically:

Secret names are listable; secret values are never returned. Even set_secret is one-way.
Spend is bounded by your account credit balance and the per-block pricing.inference_pass_through rules. A runaway loop costs you cents, not dollars.
Anonymous mode (no key) keeps the public 10-runs-per-week cap.
For less-trusted agents, mint a dedicated key with gonkablocks connect --name "agent-cursor", put it in just that client's env, and revoke it later from the web UI.

Debugging

If the agent says "no tools listed", run the server directly and watch its stderr — it logs the auth source on startup:

gonkablocks-mcp
# [gonkablocks-mcp v0.1.0] connected. auth=file server=https://blocks.gonka.gg

For deeper inspection, use the official MCP inspector to drive the server interactively:

npx @modelcontextprotocol/inspector npx @gonkalabs/blocks-mcp

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

Connect AI agents via MCP