Set up WorkerKit in Gemini.

Before you start

What you need.

A WorkerKit account, and admin access on it: choosing the key a connection will hold is an admin-only decision, on the consent page and at Fleet access alike. The Free plan is enough, no card is needed, and the human's part is about a minute.

A Gemini surface that adds a remote MCP server. Antigravity is the one that accepts a header, across the desktop app, the Antigravity CLI and Antigravity for IDEs, which share one config file. What each surface asks of a Google account is Google's to state, and this guide does not restate it.

Or the Gemini app, if the consumer surface is where you work. Google gates custom apps there: 18 or over, in the United States, signed in with a personal Google Account rather than a work or school one, Keep Activity on, English only, and set up on desktop web.

Why this route: Gemini reaches remote MCP servers, so it takes the hosted WorkerKit MCP mounts directly, nothing to install and no code to write. The two doors are not interchangeable: Antigravity documents a headers object on a remote server, Google's own example in it an Authorization bearer token, while the Gemini app documents OAuth and no header field at all.

Not the Gemini CLI. Google announced on 2026-05-19 that Antigravity CLI was generally available and that the Gemini CLI and the Code Assist IDE extensions would stop serving requests on 2026-06-18 for Google AI Pro, Ultra and free individual users, Gemini Code Assist Standard and Enterprise licences unchanged. A guide still spelling httpUrl or gemini mcp add is aimed at a command most readers no longer have. Not a REST connector either: no Gemini surface documents a user-supplied OpenAPI or REST action carrying a static bearer key, so WorkerKit's HTTPS API has no documented door here. One address is worth reading twice: workerkit.ai/mcp is the documentation page and the live mounts are on mcp.workerkit.ai, both in full in the table above.

The case for connecting at all is on the Gemini page.

Step 0. Human, under a minute

Pick the surface first.

Several products answer to the name Gemini, and they accept different credentials.

1. 01

   Antigravity: desktop app, CLI, IDE extensions

   Takes a remote server as `serverUrl` plus a `headers` object, with an Authorization bearer token in it, so both mounts fit. This is the fleet door and the rest of this guide assumes it unless a step says otherwise. It is Google's current Gemini-powered developer surface: it runs Gemini models and its config still lives under `~/.gemini/`, but it carries neither the Gemini name nor the `gemini` command.

2. 02

   Gemini app, at gemini.google.com and on mobile

   Takes a custom app by MCP server URL, authenticated by OAuth with dynamic client registration, or by credentials you enter when a server lacks it. No static header field is documented. The fleet mount fits, through step 4. The catalog mount does not: Google documents no unauthenticated option on this surface, so an anonymous server is not a documented path here and this guide will not promise one.

3. 03

   Gemini Enterprise, and Business edition

   Takes a custom MCP server with either no authentication or an OAuth 2.0 client configured by hand (authorization URL, token URL, client ID, client secret, scopes), over StreamableHTTP only, usually after an administrator allows the domain by organisation policy. The catalog mount fits the no-authentication choice. The fleet mount expects a client that registers itself rather than credentials issued in advance, so that pairing is not documented here.

Step 1. Agent, under a minute

Add the public catalog.

In Antigravity: one entry with no headers at all, which proves the wiring before any key exists. On the Gemini app, skip to step 4.

• Antigravity, in ~/.gemini/config/mcp_config.json or .agents/mcp_config.json { "mcpServers": { "workerkit-directory": { "serverUrl": "https://mcp.workerkit.ai/directory" } } }
• Or through the interface, on each Antigravity surface Antigravity 2.0: Settings (bottom left) > Customizations > Installed MCP Servers > Add MCP Antigravity for IDEs: the "..." at the top of the agent side panel > MCP Servers > Manage MCP Servers > View raw config Antigravity CLI: type /mcp in the prompt panel to open the MCP Manager Overlay

The catalog mount takes no credential at all, on either path. It is the fastest proof that the client can reach WorkerKit, and it is worth adding first for exactly that reason: if it connects and the fleet mount does not, the problem is the credential rather than the wiring.

The key must be serverUrl. Google states that legacy fields such as url and httpUrl are not supported, which is the commonest reason an entry copied from another client, or from an older Gemini CLI guide, does nothing at all. Remote SSE, streamable HTTP and websocket servers all use it; ours are streamable HTTP.

Step 2. Human, about 60 seconds

Connect your fleet in Antigravity.

Create a manager key, then add the fleet mount as a second entry with a header.

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

   Name it for the assistant that will hold it. 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 tables below say 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 the wiring step. It reaches the fleet only: no scope on it reads a mailbox, a calendar or a CRM.

• The second entry, beside the first { "mcpServers": { "workerkit-workers": { "serverUrl": "https://mcp.workerkit.ai/workers", "headers": { "Authorization": "Bearer pe_mgr_..." } } } }

A client that cannot run an OAuth flow takes the same fleet on one header instead. An account admin creates a key at https://workerkit.ai/fleet-access, copies it once, and it becomes the value of an Authorization header on the fleet mount. That header is the whole of the authentication: there is nothing to register and nothing to pre-approve. In Antigravity that header is documented rather than a workaround, and the value carries its scheme: Bearer pe_mgr_..., word and space included.

Treat that file as a secret. Google documents no environment-variable expansion inside headers, so write the key rather than a $VAR reference and assume it sits in plain text on disk: keep it in ~/.gemini/config/mcp_config.json rather than a workspace file a repository might carry. Rotating it later is one edited line.

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 place. Read key_info rather than assuming.

Step 3. Human, about 60 seconds

Or connect from the Gemini app instead.

No key is pasted here, and there is no field to paste one into. It is a sign-in.

Do this instead of step 3 rather than as well. Google's gates first: 18 or over, in the United States, a personal Google Account rather than a work or school one, Keep Activity on, English only, and setup on desktop web though it then works on mobile.

1. 01

   Give the client the URL and nothing else

   The fleet mount publishes OAuth discovery, so a client that supports it finds the authorization server on its own and registers itself. There is no client ID to create, no secret to store and no redirect address to register in advance.

2. 02

   Approve on the WorkerKit consent page

   The client sends the person to https://workerkit.ai/mcpauth. Signing in there is what proves who is connecting; nothing is typed into the assistant.

3. 03

   An account admin picks the key the client will hold

   The consent page lists the account's manager keys and can create one on the spot, so a first connect needs no visit to Fleet access beforehand. It is admin-only on the server, not just in the page: a member sees an honest notice rather than a broken screen.

4. 04

   Scopes are chosen with the key, and are the whole of the reach

   Whatever that key carries is exactly what the assistant can do, and nothing on it reaches a connected app. Narrow it now or widen it later; a new key drops into the same connection.

• On your computer, at gemini.google.com At the bottom, click Settings, then Connected Apps (not visible? open Personal Intelligence first, then Connected Apps) Under "Custom apps": the "Add a custom app link to get started" field, or "Add a custom app" if one is already connected Enter https://mcp.workerkit.ai/workers, click Next, follow the on-screen instructions Approve at https://workerkit.ai/mcpauth

Nothing is pasted into the chat on this path, which is its real advantage: the credential never passes through a message, a log or a screenshot, and revoking it later is one action in the dashboard rather than an edit inside the assistant.

Google documents one alternative on that screen: credentials of your own, under Advanced features, then Show more, for a server without dynamic client registration. WorkerKit has it, so that panel should not be needed, and there is no field there for a manager key. If a guide tells you to paste pe_mgr_... into the Gemini app, it is describing a surface that does not exist. Once connected, invoke the app by typing @ and picking it. Google warns that it does not control, monitor or secure third-party MCP servers, so expect a trust prompt: what this connection reaches is the scopes on the key an admin chose.

Step 4. Agent

Verify the scopes.

Call key_info on the fleet mount. Its scope list is the truth, not the intent.

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

It returns the account title, the key name, its scopes and expiry, and serverTimeUtc; any valid key may ask. A missing scope was either not granted or granted after the key was made, and an admin re-scopes at Fleet access. Plan against what this returns.

Step 5. Agent

Keep the WorkerKit skill.

On Antigravity a skill is a directory. The Gemini app keeps none, so it takes a Gem.

• Antigravity: write https://workerkit.ai/gemini/SKILL.md into a skill directory, personal or workspace ~/.gemini/skills/workerkit-fleet/SKILL.md (alias: ~/.agents/skills/) .gemini/skills/workerkit-fleet/SKILL.md (alias: .agents/skills/)

Agent Skills are self-contained directories that package instructions into a discoverable capability. Google documents those four paths for Gemini CLI, with the .agents spelling winning inside a tier, and states that skills carry over into Antigravity as plugins. The file is a standard skill: a name and description in its front matter, then the tool reference, the cost-field semantics and the safety rules.

The Gemini app has no equivalent file. Its nearest thing is a Gem, which bundles a name, a description, an Instructions box and optional knowledge files, so paste this content into a Gem's Instructions or attach it as a knowledge file. Failing either, re-read the same URL at the start of any session that touches the fleet.

Step 6. 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 the first-worker step and give the fleet something to do.

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 the assistant 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 7. 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 Gemini 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, the assistant 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.

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.

Least privilege

What each scope grants.

The key's scopes are exactly its reach, and a refusal names the scope it wanted. Start with the reads and add scopes as the work asks for them.

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