Set up WorkerKit in Meta Muse.

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.

Meta Muse, on any of its platforms, able to add a custom connector for a service that has an API.

About a minute of the human's time. The agent does everything except two steps: creating the key, and entering it through Muse's own credential entry.

Why this route: Muse adds an outside service as a custom connector over its API rather than as an MCP server, so it uses the plain-HTTPS WorkerKit API. The case for connecting at all is on the Muse page.

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 is the most common setup mistake, and it shows up later as an empty fleet.

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

   "Muse" 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. It goes nowhere but Muse's credential entry in step 2: not into the chat, a document, a screenshot or a file.

A key carries the scopes it was granted when it was created, not the ones that exist today. 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. Read key-info rather than assuming.

Step 2. Human and agent

Store the key where Muse keeps credentials.

The person enters it through Muse's own hosted API-key entry, never the chat. From then on the agent calls https://api.workerkit.ai directly with a bearer header.

1. 01

   Hand the key to Muse, not to the chat

   The person enters it through Muse's own hosted API-key entry, the path Muse's documentation describes as credentials.request_api_access. An agent offers that entry; it never asks for the key in a message. Muse's documentation is the authority on where that sits in its interface, and this guide does not second-guess it.

2. 02

   Let Muse hold it

   By Meta's published design, a credential you connect is stored in your own VM and inserted at the network boundary by Sentinel, so the agent only ever handles a stand-in. From here on the agent works with a reference, and the raw key must never appear in a command, a log, a file or a message.

3. 03

   Call the API directly

   There is no base URL to register and no document for Muse to ingest: the agent makes ordinary HTTPS requests to https://api.workerkit.ai, sending Authorization: Bearer pe_mgr_... on each one, and reads https://api.workerkit.ai/openapi/workers.json itself to know the operations. Muse's VM has a shell, so the wk CLI is the other shape that works: install it there and let it carry the same key.

Do not go looking for a form that takes a base URL and an API description. WorkerKit is reached by holding a credential for it and calling it, the way Muse reaches any service with an API: there is no MCP server to add and no document for Muse to ingest. If a request fails auth later, read the code the response carries rather than assuming the key is wrong; the troubleshooting table below has the full set.

Either shape works from Muse's VM: plain HTTPS requests, or the wk CLI installed there and carrying the same key. The CLI is generated from the same tool definitions the API publishes, so nothing it can do is missing from the requests, and nothing here depends on which you pick.

Step 3. Agent

Verify the scopes.

GET /api/manage/workers/key-info. The scope list it returns is the truth, whatever was intended.

• Ask the key what it can do GET /api/manage/workers/key-info

It returns the account 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. Do not proceed on a partial scope set without saying what is unavailable.

Step 4. Agent

Install the WorkerKit skill.

Fetch https://workerkit.ai/muse/SKILL.md into the skills directory Muse reads, and re-read it before first use.

• Fetch the skill file into the skills directory Muse reads (~/workspace/skills on the workspaces we have seen) mkdir -p ~/workspace/skills/workerkit && curl -fsSL https://workerkit.ai/muse/SKILL.md -o ~/workspace/skills/workerkit/SKILL.md

The file is a standard skill: a name and a description in its front matter, then the endpoint reference, the cost-field semantics and the safety rules the agent needs. Save it as workerkit/SKILL.md under whichever directory this workspace reads skills from, and re-read it before first use. The command above uses ~/workspace/skills, which is where the Muse workspaces we have seen keep them; if yours differs, use yours, because a file written where nothing reads it installs nothing.

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 2 and say so: a new account has no workers yet, and steps 1 and 2 have already proved the setup, because the key authenticated and both read scopes answered. Do not read this as a fault. With installKits and manageDeployments and the person's approval you can install a directory kit with deploy set to true and run the worker it creates (installing alone leaves a worker that cannot run until worker_deploy); otherwise setup is complete without a run.

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, or skip the run and say why.

• 1. The fleet list: report how many workers Muse can see GET /api/manage/workers
• 2. Recent runs across the fleet: confirms readRuns GET /api/manage/workers/runs?limit=5
• 3. Before running anything, read what that worker does and what it may touch. Both rides on readWorkers, and this is the step that decides whether the run is safe GET /api/manage/workers/{workerId}/instruction GET /api/manage/workers/{workerId}/permissions
• 4. 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 POST /api/manage/workers/{workerId}/run {} GET /api/manage/workers/runs/{runId}/events?afterSeq={lastSeq}
• 5. Read the receipt: costAuthority first, then modelCostUsd GET /api/manage/workers/runs/{runId}

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. It means the gate refused the run before any money moved, and on a new free account the reason is usually InsufficientCredits: the connection works, and the person tops up the wallet when they want runs. Report the skipReason rather than retrying. Then report the fleet size, the active scopes, and what the test cost, and the fleet is live.

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.

Discover recipes with GET /api/directory/mcp/authoring/tools?purpose=decision and read GET /api/directory/mcp/authoring/guide?section=decision; both are anonymous. Check connections with GET /api/manage/apps, then send the request to POST /api/manage/decision-workers. Use the returned worker with the existing deployment, run and instruction endpoints in the workers OpenAPI document. Running needs runWorkers; results need readRuns. Saved setup answers adjust categories/levels; a structural question or source change needs 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.

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 API, not advice.

Troubleshooting

Symptoms, causes, fixes.

The second table is the auth set in full, the same one the API page carries: each failure names itself in the response, so an agent never has to guess which one it met.

Not available yet

Three things Muse cannot do today, and what to do instead.

1. 01

   Sign-in with OAuth2

   The API offers OAuth2 with PKCE for platforms that register themselves, but the Muse connector platform's redirect address is not published yet, so the manager-key path above is the supported one for Muse, and it is not going away.

2. 02

   Push into Muse

   Meta publishes no inbound surface for Muse, so nothing can be sent to it. Watch the fleet with the held feed connection instead: one request for the whole fleet, and it never busy-waits.

3. 03

   A Muse delivery channel

   A worker's report reaches people through email, Slack, Teams, Telegram, Discord, Notion, SMS and WhatsApp, or a signed webhook. The day Muse can receive one, it is configuration over the webhook channel.