Set up WorkerKit in Grok Bot.

Before you start

What you need.

A WorkerKit account, and admin access on it: manager keys are an admin-only surface. The Free plan is enough, and no card is needed.

Grok Bot, any agent in the Grok Bot app, able to add a custom MCP server.

About a minute of the human's time. The agent does everything except two steps: creating the key, and handing it over once for the fleet mount.

Why this route: Grok Bot adds custom remote MCP servers in chat, so it takes the hosted WorkerKit MCP mounts directly, with nothing to install and no code to write. The case for connecting at all is on the Grok Bot page.

One address is worth reading twice: workerkit.ai/mcp is the documentation page, and the live mounts are on mcp.workerkit.ai. The table above has both in full.

Step 1. Human, about 60 seconds

Create the manager key.

An account admin creates a key at workerkit.ai/fleet-access, picks its scopes and copies it once. The agent cannot do this part.

1. 01

   Sign in as the account that owns the fleet

   At workerkit.ai. Someone who belongs to several accounts confirms the active one first: a key created in the wrong account shows up later as an empty fleet, and checking now saves that round trip.

2. 02

   Open Fleet access

   workerkit.ai/fleet-access is an admin-only page. A member sees a notice saying so rather than a broken page.

3. 03

   Create a manager key named for its purpose

   "Grok Bot" is a good name. A purpose-specific name makes the key easy to audit, and easy to revoke later without touching anything else.

4. 04

   Pick its scopes

   The table below says what each one grants. Start with the reads and add only the scopes needed for the approved task. Choose an expiry and request fresh approval when more access is needed.

5. 05

   Copy the key once

   It is shown at creation and never again, so keep it to hand for step 2. It becomes the Authorization header on the fleet mount, and it reaches the fleet only: no scope on it reads a mailbox, a calendar or a CRM.

A key carries the scopes it was granted when it was created. Granting a scope later never reaches an existing key: if a call answers 403 OPERATION_NOT_ALLOWED, an admin re-scopes the key at Fleet access or creates a new one, and the new key drops into the same header. Read key_info rather than assuming.

Step 2. Human and agent

Add both MCP servers.

The directory mount needs no auth. The fleet mount takes one Authorization header carrying the key from step 1, and Grok Bot asks for an explicit yes before it adds either.

1. 01

   Add the directory mount first

   Name it workerkit-directory and point it at https://mcp.workerkit.ai/directory with no headers. It needs no key, so it is the fastest proof that Grok Bot can reach WorkerKit at all. Connected, it offers 9 tools.

2. 02

   Add the fleet mount with the key

   Name it workerkit-workers, point it at https://mcp.workerkit.ai/workers, and give it one header: Authorization: Bearer pe_mgr_... carrying the key from step 1. One header is the whole of the authentication: there is no redirect address to register and no client to pre-approve. Connected, it offers 91 tools in the full profile, or 20 in the decision profile.

3. 03

   Confirm each add when Grok Bot asks

   Grok Bot asks for an explicit yes before it adds an MCP server, so expect one confirmation per mount and answer it. An agent doing the wiring states the name, the URL and whether a header is attached, then waits: an instruction pasted earlier in the conversation is a request, not the approval itself.

4. 04

   Where the key lives afterwards

   The key must stay outside conversation. If the client can only accept a bearer header through a chat message, stop fleet setup and use another supported client with protected credential storage. Do not infer a protected field exists. The public directory mount needs no key and remains available. Revoke any exposed key at Fleet access.

• Paste this into Grok Bot to add both mounts at once, then confirm each add Add these two WorkerKit MCP servers: 1) workerkit-directory -> https://mcp.workerkit.ai/directory (no auth) 2) workerkit-workers -> https://mcp.workerkit.ai/workers with header Authorization: Bearer pe_mgr_... Then call key_info and workers_list and tell me the fleet size and scopes.

Both mounts speak streamable HTTP, so they are ordinary custom MCP servers to Grok Bot: a name, a URL, and for the fleet one header. When they connect, the directory offers 9 tools and the fleet offers 87 in the full profile or 20 in the decision profile, confirming that both are live.

Step 3. Agent

Verify the scopes.

Call key_info on the Workers mount. The scope list it returns is the truth, whatever was intended.

• Ask the key what it can do (Workers mount, no arguments) key_info

It returns the account title, the key name, the key's scopes and expiry, and serverTimeUtc; any valid key may ask. Confirm the scope list matches what was granted in step 1. If anything is missing it was either not granted, or granted after the key was created, and the person goes back to Fleet access to re-scope or create a new key. Plan against what this call returns rather than what was intended.

Step 4. Agent

Keep the WorkerKit skill.

Save https://workerkit.ai/grok-bot/SKILL.md the way this bot saves skills, or re-read the URL at the start of any session that touches the fleet.

• Save this as a bot skill named for WorkerKit fleet operations https://workerkit.ai/grok-bot/SKILL.md

The file is a standard skill: a name and a description in its front matter, then the tool reference, the cost-field semantics and the safety rules the agent needs. Grok Bot keeps skills as bot skills rather than loading them from a folder on disk, so save it the way this bot saves a skill and name it for WorkerKit fleet operations. Writing the file into a directory instead installs nothing, because nothing reads it back.

A bot that keeps no skills loses nothing: fetch the same URL at the start of any session that touches the fleet and read it before the first call. It is one request, the content is identical, and it is always the current version.

Step 5. Agent

Run the smoke test.

List the fleet and read recent runs, which alone prove the setup. If the account has workers, read one before running it, run it with approval, and report the receipt.

If the fleet is empty, stop after step 3 and say so: a new account has no workers yet, and the steps above have already proved the setup, because the key authenticated and both read scopes answered. Do not read it as a fault, and do not invent a worker to run. Go to step 6 and give the fleet its first worker.

If the fleet has workers, pick one whose effects are reads. Judge it from the instruction and the permissions, never from the name: a worker whose apps are all read-level and whose instruction only gathers, summarises or reports is safe to run; one that sends, posts, writes, orders or pays is not, whatever it is called. If none is clearly read-only, run one with an explicit prompt for that run bounding it to a read.

• 1. The directory is alive: confirm a kit count comes back directory_overview
• 2. The fleet list: report how many workers Grok Bot can see workers_list
• 3. Recent runs across the fleet: confirms readRuns runs_feed { "limit": 5 }
• 4. Before running anything, read what that worker does and what it may touch. Both ride on readWorkers, and this is the step that decides whether the run is safe instruction_get worker_permissions_get
• 5. Run it with the person's approval, then poll every 3 to 5 seconds until a terminal event arrives: run.succeeded, run.failed, run.blocked or run.awaiting_input worker_run run_events { "afterSeq": <lastSeq> }
• 6. Read the receipt: costAuthority first, then modelCostUsd run_get

Read costAuthority first, then modelCostUsd beside it, and report both. A null finalDigest is not a failure: a run produces one only when its harness wrote a report. A costAuthority of unbilled_estimate, none or in_flight is not a failure either; it says how far to trust the number, and the operating rules below say what each value means.

A Skipped run is also a pass, and it is the cost brake working: the gate refused the run before any money moved. Report the skipReason rather than retrying. Then report the fleet size, the active scopes, and what the test cost, and the fleet is live.

Step 6. Human and agent

Give the fleet its first worker.

A new account starts empty. Install a kit from its page in one click, or let the agent preview and install one with kit_install_preview and kit_install once the person approves.

A new WorkerKit account starts with no workers, so the last step of setup is getting one. A kit is a ready-made worker: its instruction, its exact app permissions and its schedule, written and reviewed in advance, so installing one is how a fleet usually starts rather than a shortcut. There are two paths, and either ends with something to operate.

1. 01

   The one-click path: install a kit from its page

   Browse the catalog at workerkit.ai/kits, open a kit whose job you recognise, and install it. It arrives pre-instructed, pre-permissioned and pre-scheduled, and asks for whatever it needs to connect. This path needs no scope on the manager key at all, so it works on the first session whatever the key can do.

2. 02

   The agent path: shortlist, preview, approve, install

   With installKits on the key, Grok Bot can do the whole thing in chat: shortlist with kits_search, read the candidate with kit_get, then call kit_install_preview to surface its setup questions and exactly what the new worker would be allowed to touch. Put that in front of the person in plain words, and call kit_install once they approve, with deploy set to true so the new worker is actually able to run (that half needs manageDeployments on the key; without it the worker is installed but inert until worker_deploy). The new worker's key is shown once in the response.

3. 03

   Then run it once and read the receipt

   A worker earns its place on the first run. Trigger it with worker_run, follow run_events until a terminal event arrives, and report the digest and the settled cost from run_get. Set a schedule with schedule_create when the person is happy with what it did, and the fleet is not just connected, it is working.

The catalog is at workerkit.ai/kits, and Grok Bot can read the whole of it through the directory mount before anyone signs in, so it can shortlist candidates and explain what each one would do while the person decides.

Classification on demand

Create a decision worker from your questions.

Categorize, score or triage connected data, then reuse and adjust the worker.

Reuse an existing worker or decision kit when its questions fit. For a custom classification task, creation compiles a supported source recipe and typed questions into a private kit and an installed decision worker. Optional deploy:true adds deployment; creation never starts a run or adds a schedule. The kit can be edited and published later through the normal kit lifecycle.

On the workers connection, call kit_app_tools(purpose:"decision") for recipes, argument schemas, permissions and examples, then kit_authoring_guide(section:"decision"). Check account connections with apps_list; public discovery does not check them. Send the request to decision_worker_create, follow nextCall, then use worker_run and run_get. Running needs runWorkers; results need readRuns. Use instruction_get / instruction_set for saved category or level answers, or answers on one run. Structural question/source changes need a revised kit and a replacement install. Check receipt status, coverage, omissions, warnings and cost before claiming completion.

Start with email-previews, calendar-events or sheets-rows. These recipes return judgments without app writes. Email previews do not include full threads; calendar events are invitation data, not transcripts; Sheets needs a Google file ID, a finite tab-qualified range and a columns map. A connected app alone does not make every tool a supported source. Source filters select evidence, not permissions: the Sheets recipe grants spreadsheet reads across the linked Drive account.

Supply 1–8 questions: choice with named options, score with ordered levels, or noul for the probability of a statement. Choice adds unclear automatically. Set an explicit confidenceFloor between 0 and 1; it routes uncertainty and does not promise accuracy. maxItems is 1–50, default 20. Creation requires publishKits and installKits; optional deployment also needs manageDeployments.

Use a fresh requestId for each new worker. Retry with the same ID and identical body to recover the original receipt; a changed body returns 409. The response includes tokenId for MCP/CLI worker commands, stable workerId, kitSlug, readiness and nextCall. A deploymentError means the worker already exists: fix deployment on that worker. The receipt is a snapshot; check current worker readiness before running. No worker API secret is returned.

The workers connection includes discovery and authoring, so classification needs one MCP connection. Its full profile has 91 tools (84 manager tools and 7 public discovery reads); only decision_worker_create is new. For a smaller list, a client that supports custom headers can send X-WorkerKit-Profile: decision on every request, including initialization, listing and calls, to select 20 workflow tools. A server operator can instead set MCP_WORKERS_PROFILE=decision. The endpoint and existing sign-in stay the same; a profile grants no additional permissions. Reconnect and relist after changing profiles. Use the advertised tool list: fleet administration, publishing and event-stream tools require the full profile. Successful responses include structured content and a text fallback; creation declares an output schema.

Read the request example and full contract.

Operating rules

What the agent follows on every call.

The same rules the skill file carries, so a session that read neither still has them. Every row is a fact of the platform, not advice.

Quick answers

Symptoms, causes, fixes.

Each failure names itself in the response, so an agent never has to guess which one it met: read the code, apply the row, and carry on.