Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide takes you from a fresh Claude Desktop install to a fully-routed connection through Portkey in about five minutes. After setup, every conversation flows through your organization’s gateway with approved model routing, policy enforcement, and cost tracking.
Requirements: Claude Desktop with third-party inference support (any recent build from late 2025 onward). If you don’t see Configure third-party inference under the Developer menu after enabling Developer mode, update the app from claude.ai/download.

​
What you need before starting

Get these three values from your platform admin. If you’re a solo builder, follow the Platform Admin Guide first to create them yourself.

Gateway URL

https://api.portkey.ai for Portkey SaaS, or your custom URL if your org self-hosts. Confirm with your admin.

Portkey API Key

A scoped key from API Keys

Metadata Template

JSON for the x-portkey-metadata header

​
Connect Claude Desktop to Portkey

1

Enable Developer mode

Open Help → Troubleshooting → Enable Developer mode. The menu lives in the menu bar on macOS and the hamburger menu (top-left) on Windows.
Enable Developer mode option under Help → Troubleshooting in Claude Desktop on macOS
2

Open third-party inference settings

Navigate to Developer → Configure third-party inference.
Developer menu showing Configure third-party inference option
3

Set the Gateway connection

Select Gateway (Anthropic-compatible) and fill in the fields:
FieldValue
Gateway base URLhttps://api.portkey.ai
Gateway API keyYour Portkey API key
Gateway auth schemebearer
Gateway configuration panel with base URL, API key, and auth scheme fields
4

Add the metadata header

Under Gateway extra headers, add a new header:
FieldValue
Header namex-portkey-metadata
Header value(your metadata JSON)
{"tenant":"acme","user":"[email protected]","team":"engineering","env":"prod"}
Gateway extra headers panel in Claude Desktop showing x-portkey-metadata configured
Replace the values with what your platform team specifies. These fields drive analytics attribution and per-team filtering in Portkey.
5

Apply and restart

Click Apply locally. Fully quit Claude Desktop (not just close the window), then reopen it.
A simple window close keeps the old process alive. The new gateway settings only load on a full quit and relaunch.

​
Verify it works

Send any prompt in Claude Desktop, then run through these two checks.
1

Confirm the request reached Portkey

Open Portkey Logs. Your request should appear within a few seconds, tagged with the metadata you set in step 4.
Portkey Logs view showing a Claude Desktop request with metadata, model, and cost
2

Confirm the right model responded

Click the log entry. Verify the model and provider fields match what your admin configured for your team, not Anthropic’s default.
Expanded log detail showing model, provider, metadata, and cost breakdown for a Claude Desktop request
Request shows in Logs with correct metadata and the expected model? You’re done.

​
Troubleshooting

Your Portkey API key is expired, revoked, or scoped to a different workspace. Get a fresh key from your admin or generate one yourself at API Keys.
Three things to check:
  1. Base URL is correct: https://api.portkey.ai for Portkey SaaS, or your org’s self-hosted gateway URL. No trailing slash, no /v1.
  2. Auth scheme is set to bearer.
  3. You fully quit and relaunched Claude Desktop after applying settings (not just closed the window).
Metadata JSON must be valid (no trailing commas, no single quotes). Key names are case-sensitive and must exactly match what your admin configured in the policy rules.
Model routing is controlled by your admin’s config in Portkey. If you’re getting unexpected model behavior, your team’s config likely points to a different model than you expect. Check with your platform team.
Either Developer mode isn’t enabled (check Help → Troubleshooting), or your Claude Desktop build predates third-party inference support. Update the app from claude.ai/download.

​
FAQ

Yes. The menu paths differ slightly (covered in Step 1) but the gateway settings and headers are identical.
Yes, but Cowork has its own configuration surface inside Claude Desktop. See the Claude Cowork guide for the Cowork-specific setup.
Portkey adds single-digit milliseconds of overhead per request. You won’t notice it during normal use.
Claude Desktop will surface the connection error like any other API failure. If your admin configured fallbacks in the Portkey config, traffic automatically routes to a backup provider before that happens.
Yes. Third-party inference is a Claude Desktop setting independent of your account type. Your platform admin can issue you a personal-scoped API key for pilot or solo use.
Claude Desktop stores third-party inference credentials in the OS keychain (macOS Keychain or Windows Credential Manager).
Your admin will give you the gateway URL for your self-hosted deployment. It will not be api.portkey.ai. Everything else in this guide stays the same: same auth scheme, same metadata header, same setup flow.

​
Next steps

Add metadata to your traces

Tag requests with custom keys for richer filtering and cost attribution.

Group requests by session

Use trace IDs to group related prompts into a single session view.

Understand your spend

Filter analytics by team, model, or environment.

Set up alerts

Get notified before you hit budget caps.
Last modified on May 8, 2026