Set up WorkerKit in Grok Bot.

Before you start

What you need.

A WorkerKit account with admin access to create a manager key. The Free plan is enough; no card needed.

Grok Bot with support for custom MCP servers and protected credential settings for the key.

To run workers: connected apps, an enabled deployment, model funding and available budget.

Grok Bot connects to the hosted WorkerKit MCP server. See AI workers for Grok Bot for use cases.

workerkit.ai/mcp is documentation. Use the MCP server addresses in the table above.

Step 1. Human

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 AI 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. No scope gives it app credentials, but invokeActions returns an Action worker's tool results, so grant it only where an agent should call those tools.

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 AI 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 WorkerKit.

Connect WorkerKit with the key from step 1 to discover kits and manage workers. Grok Bot asks you to confirm before adding it.

1. 01

   Add WorkerKit with the key

   Name the connection WorkerKit and use https://mcp.workerkit.ai/workers. Enter Authorization: Bearer pe_mgr_... in protected credential settings using the key from step 1. Call key_info to verify the account and scopes.

2. 02

   Add Knowledge MCP when needed

   Add WorkerKit Knowledge at https://mcp.workerkit.ai/knowledge to search and read published reports. Use the same key with readKnowledge. To configure publication and reader access, also grant manageKnowledge.

3. 03

   Confirm each add when Grok Bot asks

   Grok Bot asks for an explicit yes before adding each connection. Review its name, URL and authentication, then confirm.

4. 04

   Where the key lives afterwards

   Keep the key out of chat. If the client accepts keys only in chat, stop fleet setup and use another client. Check that protected credential settings exist; never assume. Revoke exposed keys at AI access.

• Paste into Grok Bot Help me connect WorkerKit: Add WorkerKit at https://mcp.workerkit.ai/workers for kit discovery and worker management. I will enter the scoped manager key in protected credential settings, outside chat. Ask me to confirm the connection, then call key_info and workers_list. Report the account, scopes and worker count.

Use streamable HTTP.

Step 3. Agent

Verify the scopes.

Call key_info on WorkerKit to check the account and granted scopes.

• Verify WorkerKit access (no arguments) key_info

key_info returns the account, key name, scopes, expiry and serverTimeUtc. Confirm the account and scopes match the approved access. If a scope is missing, an admin must re-scope or replace the key at AI access.

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 WorkerKit https://workerkit.ai/grok-bot/SKILL.md

Save the reference as a Grok Bot skill named WorkerKit. It contains the tools, cost fields and operating rules. Grok Bot does not load skills from local folders.

If the bot cannot save skills, fetch the reference at the start of each WorkerKit session.

Step 5. Agent

Run the smoke test.

Verify the connection with fleet reads. For the first job, review the worker, deployment, funding and budget, run the approved task and inspect its result and delivery.

If the fleet is empty, the successful reads confirm the account connection. Continue to step 6 to install the first worker, connect its apps and prepare its deployment and funding. Report connection success separately from the first completed job.

Choose a small job that represents the intended use. Inspect its instructions and effective app grants, then confirm the input, expected output and any app changes with the person. For a read-only test, use a worker whose grants permit reads only; for an action kit, review and approve the specific writes. A prompt is an instruction, while app grants enforce access.

• 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. Read the job and grants, then check deployment, funding and budget headroom instruction_get worker_permissions_get onboarding_get account_usage deployments_list budget_get fleet_budget_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 identifies a readiness or budget step through skipReason. Complete that step before another attempt. A first job succeeds when its output matches the request and the intended destination receives the result. Report the run ID, outcome and cost separately from connection status, and inspect the existing run after a timeout before starting another.

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

   Check readiness and funding

   Confirm the worker and model deployment are enabled, the required apps are connected, model funding is usable and per-run, daily and account budgets permit the job. Use onboarding_get and account_usage to find the next setup action. The person completes app sign-in and any wallet checkout in the trusted page.

4. 04

   Then run it once and read the receipt

   Trigger the approved job with worker_run and keep its run ID. Follow run_events to completion and inspect the output and cost from run_get. Verify delivery to the selected destination. Once the result is useful, create the approved schedule with its time zone and inspect the first scheduled run.

Browse the kit catalog or ask Grok Bot to shortlist kits through WorkerKit.

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 createWorkers; 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 includes fleet management, app resource discovery, kit authoring and public directory reads. 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 the smaller workflow tool set. 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, Action worker 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.

App tools, no model

Call app tools through an Action worker.

One exact app operation per call, with the inputs you supply.

An Action worker (modelType: "none") exposes 1 to 64 selected app tools and has no model, instruction, schedule or deployment. Each call invokes one tool with the arguments the caller sends, under the worker's own app access, and readiness.canInvoke on worker_get says whether its tools can be called now. Run and deploy requests answer 400 action_worker_requires_invoke.

On the workers connection's full profile: action_worker_options lists apps with no tools selected; pass an explicit app for schemas and defaults (readWorkers). action_worker_create requires an explicit app or actionSpec and copies the selected app's default tools, or takes an actionSpec of 1 to 64, plus a slackConnectionId for Slack tools when the account has more than one Slack bot (createWorkers); worker_tools lists the saved tools (readWorkers); worker_tool_call calls one with arguments, plus an idempotencyKey on a write (invokeActions); worker_tool_invocation reads a write's receipt (invokeActions). Pass the returned tokenId. kits_search(modelType:"none") finds Action kits; install one with kit_install and no deploy.

An explicit actionSpec needs no app and can span native or reviewed MCP apps. Private API tools require a dashboard binding to a published version; they are not actionSpec refs.

A write tool (readOnly: false) needs an idempotency key. Repeating the key with the same arguments returns the stored receipt (a confirmation, not the app's response) without calling the app again; with other arguments it is a 409. A call answers with status succeeded, denied, failed, in_progress or outcome_unknown; branch on it, not on the HTTP code. On outcome_unknown the write may have happened: never resend it automatically, under any key; read the receipt and check the app. Each call counts toward the worker's daily request limit; a refusal marked retryable, such as usage_limit, is retried later under a new key. Only the owner changes the selected tools, in the dashboard.

Read the call examples.

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.