Claude for Microsoft 365

The Claude add-in for Microsoft 365 puts Claude in a task pane inside Excel, Word, PowerPoint, and Outlook. Point it at Portkey instead of Anthropic’s API and every request from every user routes through one governed gateway. Configuration travels in the add-in’s manifest XML, so nothing is left to individual users. Generate the manifest once, deploy it from M365 Admin Center, and the whole org is online. When you’re done:

Every task-pane conversation routes through Portkey
Model choice is pinned by config, not by the user
Budget caps, rate limits, and guardrails enforce on every request
Requests are attributed per user and team in Logs and Analytics

How it works

The add-in is hosted by Anthropic at pivot.claude.ai. You host nothing. The only artifact you produce is a manifest XML, and your gateway settings ride in it as URL query parameters on the task-pane URL.

Excel / Word / PowerPoint  ──Authorization: Bearer──>  Portkey  ──>  Anthropic / Bedrock / Vertex
        │
        └── loads pivot.claude.ai/?gateway_url=…&gateway_token=…&gateway_api_format=anthropic
                                        ▲
                                   manifest.xml

Model traffic goes from the user’s Office WebView straight to Portkey. Allow pivot.claude.ai and your gateway host through the corporate firewall.

Prerequisites

Requirement	Notes
Portkey API key with a config attached	Steps 1–3
Node.js 18+	The manifest builder runs on Node
Claude Code	Hosts the manifest generator plugin
M365 Global Admin or Exchange Admin	Required to upload to Integrated apps
Excel/Word/PowerPoint 2019+ or Microsoft 365	Windows, Mac, or web

1. Add a provider integration

Connect the upstream model source Portkey calls on your behalf. Go to Model Catalog → Add Provider.

Anthropic

Direct API access

AWS Bedrock

Cross-region inference

Vertex AI

Google Cloud platform

2. Create a config with `override_params`

The add-in sends Anthropic-API model names from its built-in model picker — claude-sonnet-4-5, claude-opus-4-5, and so on. Those names won’t resolve against your workspace’s provider slugs, so pin the target model with override_params. Go to Configs → Create Config:

{
  "override_params": {
    "model": "@anthropic-prod/claude-sonnet-4-20250514"
  }
}

The value uses @{provider-slug}/{model} addressing, where the slug is the integration from step 1.

Naming convention: m365-{team}-{env}. Examples: m365-finance-prod, m365-legal-prod.

override_params replaces the matching field in the incoming request. Whatever model the add-in’s picker sends is discarded, and every request is served by the model named here.

The model picker becomes cosmetic. Users switch models in the task pane and get identical behaviour. Collapse the picker to a single honest entry with available_models, or route on the incoming model name instead of hard-pinning it.

Configs also carry reliability features. Open the relevant section if you need them:

Add fallbacks for reliability

Route to a backup provider if the primary is unavailable:

{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "provider": "@anthropic-prod" },
    { "provider": "@bedrock-prod" }
  ]
}

See Fallbacks.

Enable caching

Reduce cost and latency for repeated prompts:

{
  "provider": "@anthropic-prod",
  "cache": { "mode": "simple" }
}

See Caching.

Route by team with conditional routing

Send different teams to different models using metadata from step 4:

{
  "strategy": {
    "mode": "conditional",
    "conditions": [
      { "query": { "metadata.team": { "$eq": "research" } }, "then": "opus-target" }
    ],
    "default": "sonnet-target"
  },
  "targets": [
    {
      "name": "opus-target",
      "provider": "@anthropic-prod",
      "override_params": { "model": "claude-opus-4-5" }
    },
    {
      "name": "sonnet-target",
      "provider": "@anthropic-prod",
      "override_params": { "model": "claude-sonnet-4-5" }
    }
  ]
}

See Conditional Routing.

3. Create the API key

Go to API Keys → create one key per team or environment.

Attach the config from step 2

Every request authenticated with this key inherits the config.

Attach budget and rate limits

See Budget Limits and Rate Limits.

Turn on Allow config override

Required. Without it the attached config does not apply to the request.

Allow config override is not optional. Left off, Portkey keeps the client’s own parameters and passes the add-in’s claude-sonnet-4-5 straight through to the provider instead of replacing it with your override_params.model. The failure is quiet — a 200 from an unintended model, or a provider error about an unknown model, with nothing naming the config as the cause.

4. Verify the gateway before building anything

A manifest pointing at an unreachable model deploys perfectly and then fails at the user’s first message. Probe first.

curl "https://api.portkey.ai/v1/messages" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer $PORTKEY_API_KEY' \
  -d '{"model": "claude-sonnet-4-5", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}'

Check two things in the response:

Check	Expected
HTTP status	`200`
`model` field	The model pinned in step 2 — not the model sent in the request

If the response echoes claude-sonnet-4-5, the override isn’t applying. Re-check Allow config override on the API key.

Use authorization, not x-api-key. The add-in supports only those two header schemes, and Portkey rejects its API key on x-api-key with Invalid API Key. Error Code: 03. Portkey’s native x-portkey-api-key works with curl but the add-in cannot send it.

5. Install the manifest generator

The manifest is built by claude-for-msft-365-install, a Claude Code plugin published by Anthropic. It fetches the canonical manifest template and appends your gateway settings as URL query parameters.

Confirm Node.js is installed

The build and validation scripts run on Node 18+.

node --version

Add the marketplace and install the plugin

claude plugin marketplace add anthropics/financial-services
claude plugin install claude-for-msft-365-install@claude-for-financial-services

Restart the Claude Code session

Slash commands register at startup. Without a restart they won’t appear.

Set the plugin path

The plugin installs to a version-pinned directory:

PLUGIN=~/.claude/plugins/cache/claude-for-financial-services/claude-for-msft-365-install/0.1.11

Check your version with ls ~/.claude/plugins/cache/claude-for-financial-services/claude-for-msft-365-install/. Inside a session, ${CLAUDE_PLUGIN_ROOT} resolves automatically.

The plugin adds these commands:

Command	Purpose
`/claude-for-msft-365-install:setup`	Guided wizard — walks the full deployment end to end
`/claude-for-msft-365-install:manifest`	Generate the manifest XML only
`/claude-for-msft-365-install:consent`	Azure admin consent URLs for Entra SSO and Outlook Graph
`/claude-for-msft-365-install:bootstrap`	Build a per-user config endpoint
`/claude-for-msft-365-install:update-user-attrs`	Per-user config via Entra extension attributes
`/claude-for-msft-365-install:access-policies`	Scope features by Purview sensitivity label
`/claude-for-msft-365-install:debug`	Diagnose a broken deployment
`/claude-for-msft-365-install:export-data`	Export a user’s chat history, skills, and MCP registrations

Update later with claude plugin update claude-for-msft-365-install@claude-for-financial-services, then restart.

Option A — guided wizard

Run the wizard and answer its prompts. It handles everything from provider choice through Admin Center upload:

/claude-for-msft-365-install:setup

Wizard step	What it asks
1. Connection path	Gateway vs. Vertex/Bedrock/Foundry. Answer gateway — Portkey is the gateway, even though it routes to Bedrock or Vertex underneath
1b. Office apps	Excel/Word/PowerPoint, Outlook, or both
2. Admin consent	Skipped unless `entra_sso=1` is needed
3. Org-wide vs per-user	Whether the gateway token is the same for everyone
4. Generate manifest	Runs the build script with your captured keys
5. Per-user config	Extension attrs or a bootstrap endpoint, if step 3 needs them
6. Verify a model	The probe from step 4 above
7. Deploy	Walks the Admin Center upload

The wizard appends every command and captured value to a setup log at ~/Desktop/claude-for-msft-365-install-setup.md. Re-running it resumes from that log instead of starting over.

Option B — generate directly

To skip the wizard, call the build script yourself. Excel, Word, and PowerPoint share one manifest. Outlook uses a different Microsoft schema and needs its own:

node "$PLUGIN/scripts/build-manifest.mjs" office manifest.xml \
  gateway_url=https://api.portkey.ai \
  gateway_token='$PORTKEY_API_KEY' \
  gateway_auth_header=authorization \
  gateway_api_format=anthropic

node "$PLUGIN/scripts/build-manifest.mjs" outlook manifest-outlook.xml \
  gateway_url=https://api.portkey.ai \
  gateway_token='$PORTKEY_API_KEY' \
  gateway_auth_header=authorization \
  gateway_api_format=anthropic \
  graph_client_id=<your-entra-app-guid>

The four gateway keys

Key	Value for Portkey
`gateway_url`	`https://api.portkey.ai`, or your self-hosted gateway URL
`gateway_token`	The API key from step 3
`gateway_auth_header`	`authorization` — the `x-api-key` default does not work
`gateway_api_format`	`anthropic` — Portkey exposes the `/v1/messages` route

Single-quote the token in shell. Portkey keys contain / and +; the builder percent-encodes them correctly, but an unquoted shell mangles them first.

Validate before uploading:

npx --yes office-addin-manifest validate manifest.xml

Outlook needs Microsoft Graph admin consent before deployment, or every user hits “Need admin approval” on first open. Run /claude-for-msft-365-install:consent first. Note that Outlook does not support the Bedrock direct path.

Version and Id

<Id>4e2fd29d-dad0-40b3-af3c-a16e347a5ddc</Id>
<Version>1.0.0.12</Version>

First deploy: leave both alone. Updating an existing deployment: bump the fourth segment of <Version>. M365 Admin Center caches by <Id> + <Version> and silently ignores a re-upload at the same version — the most common cause of “I updated it but nothing changed”.

6. Test locally, then deploy

Sideload on one machine first. This bypasses the 24–72 hour Admin Center cache entirely, and a sideloaded manifest wins over a centrally deployed one with the same <Id>.

bash "$PLUGIN/scripts/sideload-addin.sh" manifest.xml

& "$PLUGIN\scripts\sideload-addin.ps1" C:\path\to\manifest.xml

Fully quit and reopen Excel — a backgrounded app won’t rescan. The add-in appears under Insert → My Add-ins. Send a message and confirm the request lands in Logs. Remove a sideload with clear-addin-cache.sh --id <GUID> --apply. It’s dry-run by default and only ever touches that one ID.

Deploy the add-in for your organization

Open Integrated apps

Go to M365 Admin Center → Settings → Integrated apps and choose Upload custom apps.

Select the app type

App type: Office Add-in. Choose how to upload: Upload manifest file (.xml) from device, then select manifest.xml.Admin Center validates on upload — the same check as office-addin-manifest validate.

Assign users

Start with Just me or a pilot group. Widen to Entire organization once verified — assignment changes don’t require redeployment.Assign to Specific users/groups if per-user config was issued, matching exactly who was provisioned. Nested groups aren’t supported.

Accept permissions and finish

Review the requested permissions, then Finish deployment.

Repeat for Outlook

Upload manifest-outlook.xml as a separate app if Outlook was generated.

The add-in appears under Home → Add-ins in Excel, Word, and PowerPoint once it lands.

Propagation takes up to 24 hours for a fresh deploy and up to 72 hours for an update. To skip the update wait, redeploy with a fresh <Id> UUID — every client then treats it as a brand-new add-in.

Update the manifest

Rotating the Portkey key, changing the model list, or adding any config key means regenerating and re-uploading. Run the four commands in this order:

1. Regenerate with the new values

node "$PLUGIN/scripts/build-manifest.mjs" office manifest.xml \
  gateway_url=https://api.portkey.ai \
  gateway_token='$NEW_PORTKEY_API_KEY' \
  gateway_auth_header=authorization \
  gateway_api_format=anthropic \
  available_models='claude-sonnet-4-5'

2. Bump the fourth version segment

perl -i -pe 's{(<Version>\d+\.\d+\.\d+\.)(\d+)(</Version>)}{$1.($2+1).$3}e' manifest.xml

3. Confirm the bump and validate

grep -o "<Version>[^<]*</Version>" manifest.xml
npx --yes office-addin-manifest validate manifest.xml

4. Re-upload in Admin Center → Integrated apps → your add-in → Update

The build script overwrites the file. It fetches the canonical template and writes it out fresh — it never reads your existing manifest.xml. Any hand-edit is discarded, including a <Version> bump, so always bump after regenerating, never before.

Hand-editing the manifest is otherwise fine, and those edits do reach users — trimming <Host> entries to drop PowerPoint, for example. Re-apply them after each regeneration, and bump <Version> regardless of how the change was made, or Admin Center serves the cached copy.

Keep <Id> unchanged so Admin Center treats this as an update to the existing add-in rather than a second, parallel installation.

To verify a change immediately instead of waiting out the cache, clear and re-sideload on one machine:

bash "$PLUGIN/scripts/clear-addin-cache.sh" --id <GUID> --apply
bash "$PLUGIN/scripts/sideload-addin.sh" manifest.xml

Fully quit and reopen the Office app — clearing does nothing until the app re-reads on launch, and a backgrounded app counts as still running.

Attribute requests per user and team

Add inference_headers to the manifest to tag every request with metadata Portkey uses for filtering, cost attribution, and conditional routing:

inference_headers='{"x-portkey-metadata": "{\"team\":\"finance\",\"env\":\"prod\",\"app\":\"m365-addin\"}"}'

Use case	How it works
Filter Logs	Search by any field combination, e.g. `team=finance` and `env=prod`
Attribute spend	Group cost, tokens, and latency by team or environment in Analytics
Conditional routing	Route on metadata values in the step 2 config

Authorization, x-api-key, Content-Type, Host, Content-Length, User-Agent, Cookie, and any anthropic-* / x-amz-* / x-goog-* header are reserved and silently dropped — they carry the add-in’s own auth and protocol negotiation.

For per-user metadata rather than one org-wide value, issue narrower keys per team, or serve per-user config from a bootstrap endpoint (/claude-for-msft-365-install:bootstrap).

Optional configuration

Each of these is another key=value argument to the build command.

available_models — control the model picker

Overrides the picker. Users see exactly what’s listed, in order, and nothing else. List every model that should remain, not just additions.

available_models='claude-sonnet-4-5'
available_models='[{"id": "claude-opus-4-5", "label": "Opus"}, "claude-sonnet-4-5"]'

Set this to a single entry when the step 2 config pins one model, so the picker tells the truth.

mcp_servers — attach in-network tools

JSON array of MCP servers the add-in connects to directly. headers present means static auth; absent triggers OAuth discovery. Values interpolate other config keys.

mcp_servers='[{"url": "{{gateway_url}}/deepwiki/mcp", "label": "DeepWiki", "headers": {"Authorization": "Bearer {{gateway_token}}"}}]'

See MCP Gateway.

disabled_features — lock features org-wide

Comma-separated slugs in {domain}.{action} form:

Slug	Effect
`skills.authoring`	Blocks creating, editing, and uploading skills
`file.upload`	Blocks attaching files to the conversation
`web_search`	Removes native web search and fetch, which otherwise egress to a third-party provider
`thumbs`	Blocks response feedback
`addin.access`	Kill switch — the add-in refuses to run

Pair web_search with mcp_servers to substitute an in-network search tool. Unknown slugs are ignored.

auto_connect and allow_1p — the connection screen

By default users skip the connection form and land straight in chat. Set auto_connect=0 to show the form prefilled instead.The Back button to Claude.ai sign-in is hidden whenever enterprise config is present. Set allow_1p=1 to keep it.

otlp_endpoint — send traces to your collector

Routes the add-in’s OpenTelemetry traces to a collector you operate. Set the base HTTPS URL; the add-in appends /v1/traces and posts OTLP/HTTP. gRPC isn’t supported — the add-in runs in a browser WebView.Portkey also exports traces natively. See OpenTelemetry.

Security

The gateway_token in a manifest is a shared secret distributed to every user. It sits in plaintext in the task-pane URL, readable from any installed machine’s add-in cache. Don’t commit a manifest containing a live key to git.

Mitigate at the Portkey layer rather than trying to hide the key:

Scope each key narrowly with its own config, budget cap, and rate limit
Issue one key per team so revocation and rotation are surgical
Rotate on a schedule — regenerating the manifest is one command

For per-user tokens instead of one shared key, serve them from a bootstrap endpoint (/claude-for-msft-365-install:bootstrap), which returns per-user JSON config at startup and overrides manifest values.

Pre-launch checklist

Requests appear in Logs

Send a test message from the task pane. Confirm it shows in Logs with the expected metadata.

The correct model responds

Check the model field in the log entry. It should match the step 2 config, not the add-in’s picker.

Policies trigger

Test each budget cap, rate limit, and guardrail you configured.

Cost attribution is accurate

Verify spend rolls up under the right team in Analytics.

Firewall allows both hosts

pivot.claude.ai for the add-in payload, and your gateway host for model traffic.

Troubleshooting

Wrong model answers, or a provider error about an unknown model

The config isn’t applying. Confirm Allow config override is on for the API key (step 3) and that a config is attached to it.

401 or 403 from the gateway

Wrong header scheme. The add-in must use gateway_auth_header=authorization; Portkey rejects its key on x-api-key. Re-run the step 4 probe.

Updated the manifest but users see old config

Two caches. Admin Center ignores re-uploads at the same <Version> — bump the fourth segment. Then the client Wef cache holds until the app restarts; clear it with clear-addin-cache.sh --id <GUID> --apply and fully quit Office. Service-side propagation takes up to 72 hours for updates.

Add-in doesn't appear in the ribbon

Check Admin Center → Integrated apps → Users tab. Nested groups aren’t supported. If it shows under My Add-ins but has no ribbon button, the manifest’s <Hosts> is missing that app — check both the top-level <Hosts> list and the one under <VersionOverrides>.

Connection failed

The error screen has a Copy error details button. The paste shows a Request: block and a Manifest params: block with identical key names — diff them. Matching values mean the manifest went through unchanged and the problem is upstream. Raw error: is ground truth.

Reading the WebView console

macOS: quit the app, run defaults write com.microsoft.Excel OfficeWebAddinDeveloperExtras -bool true, enable Safari’s developer features, then enable your terminal under System Settings → Privacy & Security → Developer Tools. That third gate is the one everyone misses. Right-click in the task pane → Inspect Element.Windows: right-click in the task pane → Inspect. No setup needed with WebView2.

Chat history, skills, and MCP registrations live in browser storage on the user’s own machine — there is no server-side copy. On Windows the widely circulated “delete the Wef folder” fix destroys them along with the manifest cache. Export first with /claude-for-msft-365-install:export-data.

Claude Desktop

Roll out Claude Desktop across your org

Claude Code

Route Claude Code through Portkey

Configs

Routing, fallbacks, and caching

​How it works

​Prerequisites

​1. Add a provider integration

Anthropic

AWS Bedrock

Vertex AI

​2. Create a config with override_params

​3. Create the API key

​4. Verify the gateway before building anything

​5. Install the manifest generator

​Option A — guided wizard

​Option B — generate directly

​The four gateway keys

​Version and Id

​6. Test locally, then deploy

​Deploy the add-in for your organization

​Update the manifest

​1. Regenerate with the new values

​2. Bump the fourth version segment

​3. Confirm the bump and validate

​4. Re-upload in Admin Center → Integrated apps → your add-in → Update

​Attribute requests per user and team

​Optional configuration

​Security

​Pre-launch checklist

​Troubleshooting

​Related

Claude Desktop

Claude Code

Configs

Portkey is now PRISMA AIRS AI Gateway. See it in action.

How it works

Prerequisites

1. Add a provider integration

2. Create a config with `override_params`

3. Create the API key

4. Verify the gateway before building anything

5. Install the manifest generator

Option A — guided wizard

Option B — generate directly

The four gateway keys

Version and Id

6. Test locally, then deploy

Deploy the add-in for your organization

Update the manifest

1. Regenerate with the new values

2. Bump the fourth version segment

3. Confirm the bump and validate

4. Re-upload in Admin Center → Integrated apps → your add-in → Update

Attribute requests per user and team

Optional configuration

Security

Pre-launch checklist

Troubleshooting

Related