Set up WorkerKit in Microsoft Copilot.

Before you start

What you need.

A Copilot Studio agent you can edit, at copilotstudio.microsoft.com. Reaching Copilot Studio needs a Copilot Studio license, a Microsoft 365 Copilot license, or membership of the authors security group, and a trial license can build and test an agent but cannot publish one.

Generative orchestration on that agent. Microsoft states it is required to use MCP at all, and new agents default to it, so this is usually a confirmation rather than a change.

A WorkerKit account, and admin access on it: creating a manager key is an admin-only action. The Free plan is enough, and no card is needed.

A tenant that has not blocked the connector. MCP access in Copilot Studio rides Power Platform connectors, so a data policy over connectors governs this server and its tools too, and that is an admin decision rather than a WorkerKit one.

Why this route: Copilot Studio is the one Copilot surface that adds a remote MCP server by URL with a static key on a header the maker names. Microsoft 365 Copilot has no such field, so an agent built here and published to the Teams and Microsoft 365 Copilot channel is how the fleet reaches the assistant people actually have open, and the consumer Copilot app has no custom connector mechanism. Copilot Studio takes the Streamable transport only, and both mounts are streamable HTTP, so there is nothing to choose.

Why not the other doors. A declarative agent built in the Microsoft 365 Agents Toolkit can attach an MCP server, but Microsoft states that MCP plugins do not support API key authentication: the choices are Entra SSO, OAuth 2.0 authorization code, dynamic client registration and none. WorkerKit speaks dynamic client registration, so that door opens under the same redirect gate step 4 describes, and an API plugin built from an OpenAPI document may also send a bearer key, which is where the REST API fits. The one door that does not fit at all is a custom federated connector in the admin center: Microsoft requires the server behind it to expose read-only tools, and the fleet writes.

The case for connecting at all is on the Microsoft Copilot page.

Step 0. Human, under a minute

Confirm generative orchestration.

MCP tools are unreachable without it, and the failure is silent: the agent connects, calls nothing, and answers from its own knowledge instead.

• Copilot Studio: open the agent, then Settings Generative AI > Orchestration > "Use generative AI orchestration for your agent's responses?" > Yes

Microsoft is unambiguous: you must turn on generative orchestration to use MCP. New agents default to it, so this is usually a glance, and it is worth the glance because an agent on classic orchestration cannot use an MCP server and does not say so. Copilot Studio supports MCP tools and resources, not prompts, which costs WorkerKit nothing: every fleet capability is a tool.

Step 1. Human and agent, under a minute

Add the public catalog.

The catalog mount takes no credential, so it proves the wizard, the transport and the tenant policy before any key exists.

• Copilot Studio: Tools > Add a tool > New tool > Model Context Protocol Server name: WorkerKit catalog Server description: Browse the public WorkerKit kit catalog and the kit authoring guides. Server URL: https://mcp.workerkit.ai/directory Authentication: None
• Then finish in the Add tool dialog Select Create > the Add tool dialog appears > Create a new connection > Add to agent

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 second block is the step people miss. Microsoft routes the None path to Create as well, and then to the same Add tool dialog; whether a server with no auth still needs a connection object of its own is not spelled out. Either way, discovery runs once the dialog is finished, so an empty tool list right after Create is unfinished wiring rather than a bad URL.

Step 2. Human, about a minute

Create a manager key and connect your fleet.

The fleet mount takes API key authentication on a header you name yourself. Enter Authorization, and give the connection the key with its scheme.

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.

• Copilot Studio: Tools > Add a tool > New tool > Model Context Protocol Server name: WorkerKit fleet Server description: Operate WorkerKit AI workers: list, run, schedule, budget and deliver. Server URL: https://mcp.workerkit.ai/workers Authentication: API key Type: Header Header name: Authorization
• Then Create, and supply the key on the connection Create a new connection API key: Bearer pe_mgr_... > Add to agent

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.

Two details decide whether this works first time. The value carries its scheme: Microsoft documents only that the agent includes the key in its requests, and adds no scheme of its own, so enter Bearer pe_mgr_..., word and space included; a bare key arrives without a scheme and is refused. And the header name is the one thing here Microsoft has not published: it says to enter the name of the header, never names Authorization as an accepted value, and uses other names in its own header-auth examples. Authorization is what the fleet mount reads, so enter it, and if the tenant rejects it go to step 4 rather than to another header name.

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 and agent, only if step 3 was refused

The alternative: connect with OAuth 2.0.

The fleet mount is a full OAuth 2.1 authorization server, so the same screen takes an OAuth connection instead, and then no key is pasted anywhere.

One gate decides whether this path is open at all, so read it first. WorkerKit registers an OAuth client only for a redirect address on its allowlist of known assistant hosts, and no Power Platform address is on that list today: registration answers invalid_client_metadata: redirect_uri domain not allowed until the address Copilot Studio shows on its OAuth 2.0 screen is added. Read that address off the screen and ask us to allow it.

The points below are what OAuth buys once it is. The first of them holds for the dynamic flavours of Copilot Studio's OAuth option, where the client finds the authorization server and registers itself; the manual flavour asks for the endpoints and a client instead, and the two requests under it are how you get them.

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.

• 1. Register a client, once the redirect address is allowed. Send it exactly as Copilot Studio shows it: authorize rejects a redirect that was not registered curl -X POST https://api.workerkit.ai/api/oauth/register \ -H "Content-Type: application/json" \ -d '{"client_name":"Copilot Studio","redirect_uris":["<the redirect URL Copilot Studio shows>"]}'
• 2. Copilot Studio: the MCP tool, Authentication > OAuth 2.0 Authorization URL: https://api.workerkit.ai/api/oauth/authorize Token URL: https://api.workerkit.ai/api/oauth/token Client ID: the client_id from the response Client secret: the client_secret from the response Scopes: manager scope names, space separated

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.

The Scopes field is load-bearing rather than decorative. It takes WorkerKit manager scope names, the same ones in the table above, so readWorkers readRuns is the observer key. Every name has to be a real one: a name WorkerKit does not know drops the request out of the manager-key flow and lands the person on the wrong consent screen rather than erroring. What the assistant may then do is still the key the admin picks there.

Step 4. Agent

Verify the scopes.

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

• Ask the key what it can do (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. If a scope is missing it was either not granted, or granted after the key was created, and an admin re-scopes it at Fleet access or creates a new one.

Step 5. Human and agent

Give the agent its WorkerKit instructions.

For an agent with skill upload, import SKILL.md. Otherwise use concise agent instructions and add the full document as an accessible knowledge source.

• Copilot Studio: the agent, then Instructions Use WorkerKit for requests about workers, runs and kits. Start with key_info and use only available tools and granted scopes. Before a run, inspect the worker instruction, permissions and cost limits. Follow existing user authorization; confirm unapproved changes. Never expose credentials. Inspect run status, results, coverage and settled cost before reporting completion. Use the attached WorkerKit skill reference for operation details; if it is unavailable, say so rather than inventing tool arguments.

In Copilot Studio agents powered by the GitHub Copilot harness, choose Build, Skills, Add skill, then Upload a skill. That experience accepts SKILL.md or a ZIP containing it. Other agent types and tenants can expose different skill controls; use the controls documented for that experience.

For an Instructions field, paste the short text above without YAML frontmatter. Add the full file as a supported knowledge source and select that source and the configured WorkerKit tools with the instruction editor resource picker. A URL alone does not configure retrieval, and the full catalog does not belong in the instruction field.

Get the current reference from https://workerkit.ai/microsoft-copilot/SKILL.md. Where a skill package requires a named folder, use workerkit-fleet/SKILL.md to match its name metadata.

Step 6. Human, a few minutes

Publish the agent to Microsoft 365 Copilot.

This is the step that makes the fleet reachable from the assistant people already use. Nothing inside the Copilot chat app does it for you.

• Copilot Studio: Channels > the Teams and Microsoft 365 Copilot tile Keep "Make agent available in Microsoft 365 Copilot" selected > Add channel > publish the agent at least once > See agent in Teams > Add

Then, in Microsoft 365 Copilot, type @ and pick the agent. Leaving that checkbox clear publishes to Teams only: if the agent answers there and not in Copilot, this is why.

Sharing goes one of two ways. Availability options offers a link for named people, and showing it to teammates puts it in the Teams app store under Built with Power Platform. Showing it to everyone in the organization is Submit for admin approval, a tenant decision rather than a maker one. Two smaller facts save a support round trip: the tenant must allow Power Platform apps in Teams, and installation links do not work in the Teams mobile app.

Step 7. 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 8. 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, 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.

The catalog is public, so the agent can read all of it through the tool added in step 2 and explain what each candidate would do while the person chooses.

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.