Agent2GrokBot
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Agent2GrokBot
An MCP server that lets any MCP client - Cursor Desktop, WorkBuddy or another client - delegate work to a fixed, webhook-only Grok Bot peer and receive the answer in the same tool call.
Desktop agents have no inbound listener, so a webhook reply has nowhere to land.
Agent2GrokBot sits on a real HTTP address and bridges the two halves: it holds
one SSE stream open for the client while the peer reports progress and results
by POSTing callbacks. When the HTTP deadline is reached, the call degrades to a
task handle that task_get can poll; the result is never lost. Binary inputs and
outputs use a streaming blob API: webhook JSON carries signed attachment references,
never Base64 file contents, and MCP results include resource_link content blocks.
Stack: Python 3.13, uv, FastAPI, the official mcp SDK (MCP 2.0 / 2026-07-28),
SQLModel over SQLite with aiosqlite. Versions are pinned in pyproject.toml and
uv.lock. There is no hand-rolled JSON-RPC, tool schema, SSE framing or keepalive.
Architecture
flowchart LR
subgraph CD["MCP clients"]
SA["Session A<br/>task_id t-01"]
SB["Session B<br/>task_id t-02"]
end
subgraph APP["Agent2GrokBot - one FastAPI process"]
MCP["POST /mcp<br/>MCPServer - mcp SDK"]
CALL["POST /cb/{task_id}<br/>FastAPI route"]
QUEUE["asyncio queues<br/>keyed by task_id"]
DB[("SQLite<br/>SQLModel + aiosqlite")]
end
subgraph BOT["Grok Bot"]
HOOK["Webhook routine"]
SCHED["ScheduleRoutine<br/>per-task heartbeat"]
end
SA -->|"tools/call task_send"| MCP
SB -->|"tools/call task_send"| MCP
MCP -->|"POST task.created with callback and instructions"| HOOK
HOOK -->|"create"| SCHED
SCHED -->|"heartbeat / progress POST"| CALL
HOOK -->|"result POST, then delete routine"| CALL
CALL --> QUEUE
QUEUE -->|"wake the matching SSE stream"| MCP
MCP -.->|"SSE final response"| SA
MCP -.->|"SSE final response"| SB
MCP --- DB
CALL --- DBtask_id is the only routing key. Each in-flight tools/call owns one SSE
stream and one asyncio.Queue, so any number of client sessions can send tasks
to the same peer without cross-talk. session_label is audit metadata, never a
routing key.
The server talks to the peer by POST only. It never calls a routine API and never
inspects Grok Bot internals: ScheduleRoutine is requested by the instructions
text inside that POST, and the bot deletes it on completion.
The same exchange as a timeline:
sequenceDiagram
participant C as Client session
participant S as Agent2GrokBot
participant G as Grok Bot
C->>S: POST /mcp tools/call task_send
S->>G: POST task.created (task_id, callback, instructions)
G-->>S: 200 accepted (run started)
Note over S: asyncio tool awaits its task_id queue
loop every heartbeat_interval_s
G->>S: POST /cb/{task_id} heartbeat
end
Note over G,S: Any callback may declare next_heartbeat_s to extend the window
opt substantive progress
G->>S: POST /cb/{task_id} progress
S-->>C: notifications/progress
end
G->>S: POST /cb/{task_id} result
G->>G: delete ScheduleRoutine
S-->>C: final JSON-RPC response, stream closesRelated MCP server: antigravity-delegate
Quick start
git clone https://github.com/Anudorannador/Agent2GrokBot.git
cd Agent2GrokBot
uv sync # .python-version pins 3.13
uv run agent2grokbot # 127.0.0.1:7583Run the server. It binds
127.0.0.1only.GET /healthreports peer, lane, task and in-flight counts.Point an MCP client at it. Any MCP client works; the entry below is the Cursor example, in
~/.cursor/mcp.json, so restart Cursor after saving it:{ "mcpServers": { "agent2grokbot": { "url": "http://127.0.0.1:7583/mcp" } } }Do not hard-code
MCP-Protocol-Version: the SDK detects the client revision from the request envelope or the legacy handshake, so both v2 and older clients get the right response shape.Set up the Grok Bot. Paste
grokbot/SETUP-PROMPT.mdinto the Bot chat once; it installs the standing behaviour for all webhook tasks. That init prompt defines theX-A2G-*headers, so re-paste it when migrating from an older deployment. Copy the routine's webhook URL and sender key from the routine panel, then register them:peer_add(name="Grok main", peer_id="grok-main", url="<webhook URL>", secret="<sender key>", capabilities="market research and summarization")capabilitiesis free text describing what the Bot is for. It is metadata for the caller, not a restriction enforced by the server; the Bot's actual behaviour still comes from its setup prompt. Change it later withpeer_update(peer_id="grok-main", capabilities="...").Delegate. The tool only runs when the agent is told to use it:
Delegate this with
task_send(peer_id="grok-main", prompt="..."). If the result says the task is still working, calltask_getwith thattask_id.
For concurrent work, add more webhook triggers as lanes:
peer_update(peer_id="grok-main", add_lanes=[{"url": "...", "secret": "..."}])The server allocates a free lane, queues when all lanes are busy, and releases
the lane on any terminal state. task_cancel POSTs an instruction telling the
peer to delete its ScheduleRoutine.
Protocol
Client to server (fixed by MCP)
Owned by the official mcp SDK. POST /mcp answers with application/json for
a quick result, or 200 + text/event-stream for a long one. The SDK emits
notifications/progress when the tool calls Context.report_progress, sends
: ping comment keepalives every 15 seconds, sets X-Accel-Buffering: no, and
terminates the stream with the final JSON-RPC response. Peer heartbeats count as
liveness only and are never forwarded to the model.
Modern clients send Accept: application/json, text/event-stream and put the
protocol version and client capabilities in params._meta on every request; the
SDK also accepts the legacy initialize handshake. This side is specified and
cannot be renegotiated.
Server to peer (POST only)
The server sends one task.created POST containing task_id, prompt,
protocol_version, callback (URL, token, headers), attachments,
blob_upload, heartbeat_interval_s, and instructions. Attachment entries
contain metadata and an expiring signed download URL; blob_upload is the
task-scoped output endpoint. A contract block appears only while that peer is
behind the current wire contract. The peer returns 2xx immediately and works
in the background.
Two other POST events reach a peer: task.cancel, which stops work for one
task_id, and contract.updated, which is peer-scoped, carries no
X-A2G-Task-Id, and asks the Bot to migrate its own standing prompt.
Every callback goes to POST /cb/{task_id} with:
type:heartbeat,progress,result, orfailedevent_id: unique per callback, for idempotencyBearer <callback_token>andX-A2G-Signature: per-task credential plus HMAC over timestamp and raw body
Only an explicit result completes a task; silence is never completion. A
background sweeper marks a task stale after A2G_MISS_THRESHOLD times the
current liveness interval without a callback.
Binary attachments
Files never travel inside webhook JSON or the SQLite database. The default layout
is agent2grokbot.db beside blobs/; A2G_BLOB_DIR can override the directory.
Uploads stream to a temporary file, verify size and SHA-256, then atomically move
to blobs/<blob_id>. SQLite stores only metadata and task ownership.
Agent input. Upload raw bytes with the admin Bearer token when configured:
curl -sS -X POST "$A2G_BASE/v1/blobs?filename=meeting.mp3" \
-H "Authorization: Bearer $A2G_ADMIN_TOKEN" \
-H "Content-Type: audio/mpeg" --data-binary @meeting.mp3The 201 response is {blob_id,name,mime_type,size,sha256}. Bind one or more
IDs when dispatching; an unbound input can be attached only once:
task_send(peer_id="grok-main", prompt="Transcribe the recording",
attachment_ids=["b-..."])task.created.attachments[] adds url and expires_in_s. Grok Bot downloads
each URL with HTTP GET. URLs are task-scoped HMAC tickets and expire after
A2G_BLOB_URL_TTL_S; they are not permanent public links.
Grok Bot output. Compute the file's SHA-256 hex digest and sign the UTF-8
bytes <task_id>.<sha256> with the callback token and the normal
X-A2G-Signature timestamp scheme. POST the raw bytes to blob_upload.url with:
Authorization: Bearer <callback_token>X-A2G-SHA256: <hex>and the signature described aboveContent-Type: <file MIME type>and?filename=<name>
This signs the digest rather than the full body, so large uploads remain streamed. The server verifies the digest after writing. Then complete the task with attachment IDs only:
{"type":"result","task_id":"t-01","event_id":"t-01-r",
"result":{"text":"Transcription complete",
"attachments":[{"blob_id":"b-..."}]}}The server accepts an output ID only if that same task uploaded it. MCP
task_send and task_get responses keep the JSON summary as their first text
block and append one MCP resource_link per file. task_get generates fresh
signed URLs. Arbitrary remote URLs are never fetched by the server.
A2G_WEBHOOK_MAX_BYTES limits outbound and inbound JSON metadata, not blob
bytes. A2G_BLOB_MAX_BYTES and A2G_MAX_ATTACHMENTS limit binary size and
attachment count.
Contract channel
The wire contract is versioned in src/agent2grokbot/contract.py. That file is
the single source of truth for what a Bot must know, and it exists so an
upgraded server does not require re-pasting the setup prompt into every Bot.
Each released version records added, changed, removed and prompt_patch,
where prompt_patch is the exact text a Bot folds into its own standing
instructions. Entries are append-only: a mistake is corrected by the next
version, never by editing history.
Three mechanisms carry a change to a Bot:
Every
task.createdcarriesprotocol_version. When the target peer has not yet acknowledged that version, the payload also carries acontractblock withyour_version,changes[], the concatenatedprompt_patchand a peer-scopedack_url. A migrated peer gets no block, so the webhook stays small.contract.updatedis a push-only event sent bycontract_broadcast, for Bots that must migrate while no task is in flight. It is peer-scoped, so it carries noX-A2G-Task-Idheader.A Bot acks by echoing
protocol_versionin any heartbeat or result callback, or by POSTing{"protocol_version": "..."}to theack_urlfrom the broadcast. Version records only move forward, so a late duplicate cannot rewind a peer.
POST /v1/contract/ack?peer_id=&expires=&ticket= is authenticated by a
peer-scoped HMAC ticket, not the admin token, so a Bot can ack without holding
a server secret.
Operator workflow after a protocol change:
1. append a Change entry with the new prompt_patch (contract.py)
2. contract_get(version="<previous>") # review the delta
3. contract_broadcast(dry_run=true) # inspect the payload
4. contract_broadcast() # push to every enabled peer
5. contract_status() # see who has ackedcontract_status is the adapter dashboard: each peer reports its recorded
protocol_version, up_to_date, and the pending_versions it still owes.
Adaptive heartbeat timing
The peer owns its timer. A batch data-fix step can run far longer than the
initial heartbeat_interval_s, so any heartbeat or progress callback may
declare when it will check in next:
{"type":"heartbeat","task_id":"t-01","event_id":"t-01-hb-4",
"next_heartbeat_s":1800,"ts":1762400000}Input | Where | Meaning |
| JSON body or | Seconds from now |
| JSON body or | Absolute unix epoch seconds |
Body fields take precedence over headers, relative values over absolute ones.
The server stores the latest value on the task (clamped to 1..86400 seconds),
echoes it back as next_heartbeat_s in the 200 response, and uses it for
liveness. Invalid values are ignored, so a malformed hint never breaks a
callback; with no hint, the original heartbeat_interval_s stays in effect.
Declare a longer window before a long batch step, then shorten it again when the
work speeds up. A terminal result still ends the task.
Long tasks
If task_send reaches A2G_SSE_MAX_S, it returns a normal
resultType: "complete" response containing a task handle; the agent then calls
task_get. The task keeps running in the background. SSE keepalives defeat
proxy idle timeouts, not a hard client deadline, which is why the handle exists.
Tools
Tool | Purpose |
| Peer CRUD, including a free-text |
| Dispatch and stream the result in one call. Accepts |
| Read status and result, including after an SSE deadline. |
| Cancel, notify the peer, release the lane. |
| Read the wire contract. With |
| Per-peer migration dashboard: recorded |
| Push |
Choosing a peer
Tool schemas are static and contain no registry data, so call peer_list before
dispatching. Each peer returns id, name, capabilities, enabled and its
lanes. Select the peer_id whose capabilities fits the work and pass it
explicitly to task_send; there is no capability-based auto-routing. Lanes are
concurrency slots for one peer, not a list of specialists. session_label
groups tasks for audit purposes and never affects routing.
Tool schemas are generated from Python type hints by the SDK; Context is
injected for progress reporting and is not exposed in the schema.
Configuration
Variable | Default | Meaning |
|
| SQLite file (WAL) |
|
| Base for callback URLs and the allowed Host |
| empty | Bearer token required on |
| empty | Additional comma-separated MCP Host patterns, e.g. |
|
| HMAC key for per-task callback tokens |
|
| Initial interval; the peer may override it per callback |
|
| Missed current intervals before |
|
| Deadline before degrading to a task handle |
|
| Binary storage directory |
|
| Maximum bytes per uploaded file (100 MiB) |
|
| Signed download URL lifetime; minimum effective is 60 |
|
| Maximum input or output references per task |
|
| Maximum webhook/callback JSON metadata size (256 KiB) |
|
| Set to |
The 300s interval and 2 misses match the five-minute floor of Grok Bot
scheduled watches. Lower them only when the peer heartbeats from its work loop.
Outbound POSTs carry Authorization: Bearer <sender key>, X-A2G-Signature
(HMAC-SHA256 over timestamp and raw body), X-A2G-Delivery and
X-A2G-Task-Id. Callbacks use a per-task token with the same signature
scheme, a 300-second replay window, and (task_id, event_id) deduplication.
Callbacks after a terminal state get 410.
Deployment and authentication
A remote MCP client and a public-internet Grok Bot both need a front end.
A2G_PUBLIC_BASE_URL must be that front end's URL: it builds callback.url,
attachment download URLs and blob_upload.url for the Bot and adds its Host
to the SDK's DNS-rebinding allowlist. The public base remains the single generated
callback/download host, but MCP clients may connect through additional interfaces
listed in A2G_ALLOWED_HOSTS. For example, A2G_ALLOWED_HOSTS=100.x.y.z:*
allows a Tailscale IP without changing the URLs sent to Grok Bot.
Cloudflare Tunnel
# Terminal 1 - quick tunnel, copy the https://<name>.trycloudflare.com URL
cloudflared tunnel --url http://127.0.0.1:7583
# Terminal 2
A2G_PUBLIC_BASE_URL=https://<name>.trycloudflare.com \
A2G_ADMIN_TOKEN=<long-random-token> \
uv run agent2grokbotFor a stable hostname, use a named tunnel with an ingress rule pointing
a2g.example.com at http://127.0.0.1:7583, then set
A2G_PUBLIC_BASE_URL=https://a2g.example.com. Cloudflare Access can sit in
front: give the client a service token via CF-Access-Client-Id and
CF-Access-Client-Secret headers, and add bypass policies for /cb/*, /v1/blobs/* and /v1/tasks/*/blobs, or
the Grok Bot cannot call back, download inputs or upload outputs. Keep the agent
upload route POST /v1/blobs behind Access or the admin token.
Tailscale
# Private: tailnet members only, https://<machine>.<tailnet>.ts.net
tailscale serve https / http://127.0.0.1:7583
# Public: the same hostname opened to the internet, so Grok Bot can call back
tailscale funnel https / http://127.0.0.1:7583
tailscale funnel statusFunnel listens on 443 / 8443 / 10000 only and terminates TLS. Set
A2G_PUBLIC_BASE_URL=https://<machine>.<tailnet>.ts.net. Serve alone does
not work here: Grok Bot is not on the tailnet, so it cannot reach
/cb/{task_id} and every task would go stale. Serve injects
Tailscale-User-Login identity headers and honours tailnet grants; Funnel has
no built-in authentication at all.
Credentials
Path | Credential | Notes |
|
| Only when the env var is set. No OAuth, no mTLS, no per-user identity. |
| none | Counts only, no secrets. |
|
| Same optional admin guard as |
| task-scoped signed URL | HMAC ticket and expiry in the query string; no admin or callback token in the URL. |
| callback token + digest-bound HMAC signature | Grok Bot output upload; SHA-256 is verified after streaming. |
|
| Per-task token, 300s replay window, |
| peer-scoped signed ticket | Contract acknowledgement; no server secret required by the Bot. Ticket is HMAC-bound to |
|
| Lane secret registered by |
AdminTokenMiddleware is pure ASGI and guards only /mcp, so it never buffers
the SSE stream. The SDK's DNS-rebinding check validates Host and Origin; it is
not authentication. TLS from cloudflared or Tailscale protects the transport,
but the application-level credential is still the Bearer token.
With a public front end, always set A2G_ADMIN_TOKEN and add
"headers": {"Authorization": "Bearer <token>"} to the agent2grokbot entry
in ~/.cursor/mcp.json.
Development
uv run python -m unittest discover -s tests -t . -v
uv build
uv lock --checkThe suite is fully async (IsolatedAsyncioTestCase, httpx.ASGITransport, a
mocked webhook transport). It covers SDK-generated MCP 2.0 wire shapes and
version errors, the legacy handshake, peer CRUD, lane allocation and queueing,
callback auth and dedupe, adaptive heartbeats, stale detection, cancellation,
SSE progress frames, deadline degradation, and three concurrent sessions
sharing one peer.
Client skill
skills/agent2grokbot/ is a standard skill
folder for any MCP client or coding agent. It documents the discovery-first
workflow, calling prerequisites, full parameter and return values, limitations
and typical scenarios. Copy or link the directory into an agent's skills path,
or read SKILL.md directly before delegating.
Field notes
Failures observed in real deployments, and what each one actually means. Most "the Bot is broken" reports in this project turned out to be one of the first three.
Every task goes stale and the Bot never calls back
Check what URL the Bot was told to use before touching the Bot:
curl -sS "$A2G_BASE/health"
grep A2G_PUBLIC_BASE_URL /etc/agent2grokbot.envIf A2G_PUBLIC_BASE_URL is a LAN address (192.168.x.x), loopback, or a
100.x.y.z Tailscale address, a cloud-hosted Bot can open the webhook but
cannot reach /cb/{task_id}, /v1/blobs/*, or /v1/tasks/*/blobs. The
symptom is identical whether the Bot failed or the network did, so verify from
outside the network first:
curl -sS "https://<public-base>/health"A 200 from an external host proves the ingress; anything else means the Bot
was never at fault. Outbound delivery working while callbacks fail is the
signature of this bug, because the two directions use different networks.
The wake runs but nothing arrives
The webhook endpoint accepting a delivery (200 with a runUuid) only means
the run was queued. It says nothing about the callback network path. Distinguish
the two by posting a no-op payload with the same credentials and reading the
response body; {"success":true,"runUuid":...} confirms delivery acceptance,
not reachability.
Also compare last_seen_at across tasks. A lane whose last activity is days old
means no task has moved through that peer since then, which rules out "it worked
before the upgrade".
Funnel is refused
tailscale funnel needs both HTTPS certificates and the funnel node
attribute. The failure modes are distinct:
500 ... your Tailscale account does not support getting TLS certs → enable HTTPS Certificates
Funnel is not enabled on your tailnet → approve the funnel link
No serve config → the command never completedsocket "funnel" has hanging behaviour when either gate is closed, so run the
command under timeout and check tailscale funnel status afterwards rather
than assuming a silent hang means success.
Two supervisors fight over the port
systemd-run --user creates a transient unit: it does not survive a reboot,
Restart=on-failure misses clean exits, and secrets passed with --setenv show
up in systemctl cat. If a persistent unit also exists, the second one
crash-loops on address already in use:
ERROR: [Errno 98] error while attempting to bind on address ('0.0.0.0', 7583)Check systemctl show -p NRestarts on the persistent unit. Keep exactly one
supervisor, keep the environment in a mode-0600 EnvironmentFile, and verify
with kill -9 $(systemctl show -p MainPID --value <unit>) that the process
comes back with a new PID.
A restart silently breaks callbacks
An ephemeral tunnel hostname changes on every restart. If A2G_PUBLIC_BASE_URL
points at a quick tunnel, callbacks break the moment the tunnel is recreated,
with no error anywhere except tasks going stale again. Use a stable hostname,
or treat the tunnel URL as configuration that must be re-read after restarting
it.
Version skew after an upgrade
Before debugging a Bot against new behaviour, run contract_status. A peer with
up_to_date: false is running an older contract and is behaving exactly as its
version specifies; push contract_broadcast before concluding anything else.
Limitations
The client does not wake itself. This covers a reply arriving while a conversation is running, not waking the client from the background. That requires driving
cursor-agent --printfrom an external watcher, which is the Cursor-specific example.SSE keepalive defeats idle timeouts, not hard client deadlines. The SDK pings every 15 seconds;
A2G_SSE_MAX_Sis a deployment value, and exceeding it degrades totask_getpolling.Single generated public base. Callback and blob URLs use
A2G_PUBLIC_BASE_URL; additional MCP client Host patterns inA2G_ALLOWED_HOSTSdo not change URL generation.Single process. Subscriber queues live in memory. A multi-replica deployment needs pub/sub so a callback can reach the instance holding the SSE stream.
No message or blob eviction.
agent2grokbot.dbandblobs/grow indefinitely; set an external retention policy appropriate for the stored content.Peer liveness is threshold-based. Only a refused connection at dispatch is detected instantly; a peer that dies mid-task is detected after missed heartbeats.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Lets your agent find the right MCP server, tool or service for a task, in one call. Ads labelled.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables an agent to hand off bounded tasks to Gemini Flash through the Google Antigravity CLI, receiving live tool-progress notifications and a single compact final result over one MCP call. It runs event-driven with no polling, keeping raw events and evidence local while failing closed on errors, cancellation, or deadlines.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to ask a Grok Bot routine a question and receive the answer as a synchronous tool result, bridging the bot's asynchronous webhook callback.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to invoke Grok Bot through a webhook and receive synchronous tool results from its asynchronous callbacks, with run management, cancellation, and budget guardrails.70 npm1MIT