Skip to main content
Glama

grokbot-mcp

English | 日本語

A Cloudflare Worker that turns Grok Bot's (Cursor automation webhook) async callback into a synchronous MCP tool result.

CI License: MIT

TypeScript Cloudflare Workers Durable Objects MCP Zod Vitest Bun

Deploy to Cloudflare

MCP client ─ask_grokbot→ Worker ─POST {message, run_id, callback_url}→ Grok Bot
MCP client ←answer_text─ Worker ←POST /callbacks/{run_id}/{token} {answer}─ Grok Bot

Structure

One run = one Run Durable Object. Waiters live in DO memory; state lives in DO storage.

File

Role

src/index.ts

Worker entry. MCP tools, callback auth and intake, webhook dispatch

src/oauth.ts

/mcp authentication (API key or GitHub OAuth), GitHub sign-in, and the /oauth/token refresh guard

src/util.ts

Shared helpers (JSON responses, constant-time compare, SHA-256 hex)

src/run.ts

Run DO. Run state, waiting, TTL / retention alarms

src/budget.ts

Budget DO. Per-minute and daily counters for ask_grokbot

src/oauth-state.ts

OAuthStateGuard DO. Atomic one-time consumption of GitHub OAuth callback state

src/oauth-guard.ts

OAuthAdmissionGuard and OAuthTokenGuard DOs. Global/IP admission control, single-use code redemption, refresh retry and grant-revocation state

patches/@cloudflare%2Fworkers-oauth-provider@1.1.0.patch

Reproducible provider patch passing Worker Env and refresh-current status to the token callback

src/config.ts

Validation of vars (fail-closed when invalid)

test/bridge.test.ts

Integration tests on the Workers runtime (vitest-pool-workers)

Related MCP server: Grok Ally

MCP tools

Endpoint: POST /mcp. Authenticate with Authorization: Bearer $MCP_API_KEY (or X-API-Key), or with GitHub OAuth (see Authentication).

Tool

Purpose

ask_grokbot(message, wait_seconds=60)

Send to the webhook and wait for the callback. Returns webhook_failed if the webhook fails

wait_for_grokbot_answer(run_id, timeout_seconds=60)

Keep waiting on a pending run

get_grokbot_run(run_id)

Fetch a run

cancel_run(run_id)

Cancel a pending run

status: pending / answered / cancelled / expired. Waits are capped by MAX_WAIT_SECONDS (max 300). All of /mcp is limited by MCP_RATE_LIMITER (60 req/min, per location) and returns 429 beyond that.

Callback (Grok Bot → Worker)

  • callback_url is /callbacks/{run_id}/{token}, where token is HMAC-SHA256(CALLBACK_SIGNING_SECRET, run_id). The Worker verifies it before reading the body or waking a DO, so forged callbacks are rejected with 403 and incur no DO charges.

  • POST {"answer": "..."} to callback_url. If run_id is included it must match the URL, otherwise 400 run_id_mismatch.

  • The answer is extracted in the order answer → message → content → text → output → result; if none is present, the whole body as JSON becomes answer_text.

Status

Meaning

400

invalid_json / body_must_be_object / run_id_mismatch

403

invalid_token

404

unknown run

405

non-POST

409

already_answered / already_cancelled

410

expired

413

body over 256KB

503

callback_secret_not_configured / misconfigured

Setup

With the button: Click Deploy to Cloudflare above. The repository is cloned into your GitHub / GitLab and deployed with its Durable Objects; the OAUTH_KV namespace is created automatically. Enter the secrets it asks for (CURSOR_WEBHOOK_URL, CURSOR_WEBHOOK_API_KEY, MCP_API_KEY, CALLBACK_SIGNING_SECRET) and you can connect right away with MCP_API_KEY. GitHub OAuth is optional and can be added later.

With the CLI:

bun install
wrangler secret put CURSOR_WEBHOOK_URL
wrangler secret put CURSOR_WEBHOOK_API_KEY
wrangler secret put MCP_API_KEY              # openssl rand -hex 32
wrangler secret put CALLBACK_SIGNING_SECRET  # openssl rand -hex 32 (a different value)
bun run deploy

OAUTH_KV has no fixed ID in wrangler.jsonc: the first deploy creates it and later deploys reuse the bound namespace.

Authentication

/mcp accepts two kinds of credentials:

Method

Needs

Use for

API key

MCP_API_KEY

Quick start, CLI harnesses (Claude Code, Cursor, curl)

GitHub OAuth

GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / GITHUB_OWNER_ID

ChatGPT / dot and any Remote MCP OAuth client; per-client, expiring, revocable tokens

Anyone holding MCP_API_KEY has full access, and the key cannot be revoked per client. Once every client uses OAuth, delete it (wrangler secret delete MCP_API_KEY) to make the bridge OAuth-only.

GitHub OAuth setup (optional)

Sign-in uses a GitHub OAuth App and only the configured account can receive an MCP token. OAuth stays disabled (/authorize returns 503) until all three values below are set.

  1. Register a GitHub OAuth App with the Authorization callback URL https://<worker-host>/oauth/github/callback.

  2. Set the app's Client ID, its Client Secret, and the numeric GitHub user ID allowed to use this bridge (gh api user --jq .id):

    wrangler secret put GITHUB_CLIENT_ID
    wrangler secret put GITHUB_CLIENT_SECRET
    wrangler secret put GITHUB_OWNER_ID

    GITHUB_CLIENT_ID and GITHUB_OWNER_ID are not secret, so dashboard vars also work; keep_vars keeps them across deploys.

  3. Add https://<worker-host>/mcp as a Remote MCP server in ChatGPT, dot, or another client and complete the GitHub sign-in/consent flow. The Worker publishes OAuth metadata and supports dynamic client registration.

Item

Path

MCP server

/mcp

Protected-resource metadata

/.well-known/oauth-protected-resource/mcp

Authorization-server metadata

/.well-known/oauth-authorization-server

Authorization endpoint

/authorize

Token endpoint

/oauth/token

Dynamic client registration

/oauth/register

Scope

grokbot:use

The client should start with the MCP server URL and discover OAuth metadata automatically. After GitHub consent, verify with tools/list; do not call ask_grokbot as a connectivity probe.

The OAUTH_KV binding stores OAuth client, authorization-code, and token state.

Unauthenticated OAuth routes are limited to 20 requests per IP per minute and 120 total per minute by strongly consistent Durable Object counters. The global and per-IP checks share one transaction; either rejection leaves both counters unchanged. OAuth POST bodies are capped at 64 KiB and oversized streams are cancelled. Downstream authorization codes are atomically consumed only after the provider validates client, redirect URI, resource, and PKCE. A definitive KV 429 before the grant write releases the code reservation for retry. A failed refresh releases its reservation when the grant still points at the presented token; once the grant may have rotated, it stays fail-closed. Refresh retries for the same request receive the identical token response for 10 seconds; the cached response is AES-GCM encrypted with a key derived from CALLBACK_SIGNING_SECRET, then the response body is removed while its hash history remains. Authenticated grant revocation also invalidates the retry cache. Reuse after that window revokes the grant and its token family. A grant is also revoked after 1,000 successful rotations to bound replay history; a cached retry is checked before that cap. If another refresh arrives while the first response is being committed, the server returns 503 with Retry-After so the client can retry.

Create a Grok Bot routine (trigger: Webhook) and put its POST URL and Key into CURSOR_WEBHOOK_URL / CURSOR_WEBHOOK_API_KEY. Example Instructions (kept in Japanese, as used with the routine; translate as you like):

Webhook で起動したら、ペイロードを読む。test: true / 空ボディ / 依頼文が無いものは無視する。
message を依頼文として扱い、回答を作る。ペイロードの run_id をそのままエコーし、新しい ID を発行しない。
1. callback_url に JSON を POST する(Content-Type: application/json、User-Agent: grokbot-bridge-callback/1。
   Authorization ヘッダは付けず、着信 webhook のキーは転送しない)。
   ボディ: {"ok": true, "run_id": "<着信UUID>", "answer": "<回答全文>"}
2. callback_url には疎通確認・test の POST を送らない。最初の POST が必ず回答全文であること。
3. 再送は通信エラーまたは 5xx のときだけ 1 回。4xx は再送しない。
4. このチャットには「回答: <要約>」「run_id: …」「callback: HTTP <ステータス>」だけを投稿する。

In short, the routine must: echo the incoming run_id, POST the full answer to callback_url with no Authorization header, retry once only on network errors or 5xx, and never send probe/test POSTs.

  • Set the User-Agent explicitly. Python-urllib's default UA is blocked by Cloudflare with 1010 (403) before reaching the Worker.

  • The first callback to arrive finalizes the answer (later ones get 409). A probe POST would become the answer.

Connecting MCP clients

The transport is Streamable HTTP (not stdio). URL: https://<worker>.workers.dev/mcp. The examples below use MCP_API_KEY. For OAuth clients (ChatGPT / dot, or Claude Code without --header), register only the URL and sign in with GitHub.

Claude Code:

claude mcp add --transport http grokbot https://<worker>.workers.dev/mcp \
  --header "Authorization: Bearer $MCP_API_KEY"

JSON config (Claude Code's .mcp.json expands ${VAR} from the environment; for clients that don't, write the value directly):

{
  "mcpServers": {
    "grokbot": {
      "type": "http",
      "url": "https://<worker>.workers.dev/mcp",
      "headers": { "Authorization": "Bearer ${MCP_API_KEY}" }
    }
  }
}

Cursor's mcp.json has the same shape (type may be omitted). Never commit the key to the repository.

Check the connection (you should see the four tool names):

curl -s https://<worker>.workers.dev/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | grep -o '"name":"[a-z_]*"'

Local development

Copy .dev.vars.example to .dev.vars, fill in the values, and run bun run dev. Tests: bun run test. Type check: bun run typecheck.

Cost guardrails

Guardrail

What it caps

Where

ASK_PER_MINUTE_LIMIT (default 10)

Global per-minute ask_grokbot count. Beyond it: rate_limited + retry_after_seconds

wrangler.jsonc vars

ASK_DAILY_LIMIT (default 200, UTC day)

Daily ask_grokbot count. Beyond it: daily_limit_reached

same

COST_KILL_SWITCH="1"

Stops ask_grokbot immediately (disabled)

same (deploy after changing)

MCP_RATE_LIMITER (60/min)

All /mcp calls (including wait / get). Beyond it: 429. Approximate, per location

wrangler.jsonc ratelimits

HMAC callback token

Body reads and DO wake-ups from forged callbacks

CALLBACK_SIGNING_SECRET

message 20,000 chars / webhook timeout 10 s

Per-request input size and webhook wait

constants in src/index.ts

MAX_WAIT_SECONDS / CALLBACK_TTL_SECONDS / RUN_RETENTION_SECONDS

Single wait, deadline for the answer, retention after finish (0 = keep forever)

vars

  • Limits are counted exactly in a single DO, Budget("global"). A rejected ask creates neither a webhook call nor a Run DO.

  • An ask whose webhook returned 4xx was not accepted, so its slot is refunded and the run is cancelled. A 5xx may mean the routine already started, so the Worker does not send a second webhook and leaves the run pending; a later callback can still store the answer, and the slot is not refunded. Timeouts (10 s) and connection drops still cancel the run and are not refunded.

  • If a var is not a valid number, /mcp and callbacks return 503 misconfigured (the service never runs with limits disabled).

  • Remaining worst case (estimate): even if the daily limit is used up every day at maximum wait, the DOs stay around 800 requests and 4,500 GB-s per day, within the Free daily allowance and the Paid monthly free allowance. Grok Bot / Cursor usage is capped at ASK_DAILY_LIMIT per day.

  • Unauthenticated /mcp requests and callbacks with a bad token cost only Worker request charges ($0.30/M).

Set these up manually:

  • Cloudflare dashboard → Billing → Billable Usage → budget alert (notifies only; it does not stop usage)

  • A spend limit on the Cursor side

License

MIT. See SECURITY.md for reporting vulnerabilities.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to manage Grok Bots through MCP: create, list, search, and delete bots, send and receive messages, read conversation transcripts, search message history, and check usage.
      11
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients like Codex and Claude Code to start or continue conversations with Grok Build, track progress, read completed answers, and cancel running turns using an existing Grok login.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables external MCP clients to invoke governed tools with schema validation, budgets, policy checks, human approval for side-effecting actions, and prompt-injection quarantine.
      MIT