Skip to main content

Base URLs, auth settings, the Warpy API key, MCP connections, and custom headers power every request path. If this step is wrong, browser backend calls, MCP calls, and widget token refresh will fail.

​
Warpy API Key

API Config is also where you manage the single user-scoped Warpy API Key. Use it to:
  • copy the current key
  • rotate the key
  • copy the coding-agent handoff prompt
The same key is reused for:
  • direct Warpy API access
  • coding-agent control-plane access
  • signed widget token exchange

​
Base URLs

Base URLs tell the widget where to send backend tool requests for each environment. At minimum, create:
EnvironmentPurposeExample
locallocal developmenthttp://localhost:8000
productionlive environmenthttps://api.yourcompany.com
The selected environment on Activate Agent is what powers the install snippet.

​
Authentication

Use the auth section to tell Warpy how backend requests should authenticate.

​
Authorization header

If your API expects an Authorization header, choose:
  • the browser storage source: localStorage or sessionStorage
  • the exact storage key
  • the auth type: Bearer, Basic, or No prefix
Warpy reads the stored value, formats the header if needed, and sends it with each backend request.

​
Send browser cookies with requests

If your app authenticates browser requests with cookies, enable Send browser cookies with requests. Warpy does not ask for a cookie key for auth in this mode. Instead, it sends customer-owned requests with credentials: "include" so the browser attaches cookies normally. This works with HttpOnly auth cookies because the browser sends them directly. Warpy does not try to read them in JavaScript.

​
Session headers

Session headers map values from browser storage into outgoing request headers. Supported storage sources:
  • localStorage
  • sessionStorage
  • JavaScript-readable cookies
For each mapped header, the widget:
  1. reads the stored value from the browser
  2. builds the request header
  3. sends the backend tool request to your configured base URL
Widget -> Browser storage : read configured key
Browser storage -> Widget : token or value
Widget -> Widget          : build request headers
Widget -> Customer API    : fetch baseUrl + path
Customer API -> Widget    : response

​
MCP connections

Use MCP connections when you want Warpy to discover and call tools from a remote MCP server directly, without importing those tools into Features. Each MCP connection stores:
  • a connection name
  • the MCP server URL
  • one auth mode:
    • None
    • Static headers
    • Token exchange

​
Static headers

Use this when the MCP server always expects the same header values for every request from your workspace. Warpy stores the header map server-side and sends it on each MCP request.

​
Token exchange

Use this when the MCP server should run as the currently signed-in user. In this mode:
  1. the widget calls your token-exchange endpoint using the user’s existing browser session
  2. your app returns short-lived MCP headers for that user
  3. Warpy uses those headers only for the active run
The endpoint should return: 
{
  "headers": {
    "Authorization": "Bearer <short-lived-token>"
  },
  "expiresAt": "2026-04-20T12:00:00Z"
}
Warpy does not store those per-user headers long-term, and this flow avoids extra login prompts in the widget.

​
How to find the right storage key

  1. Sign in to your product.
  2. Open browser DevTools.
  3. Check Application or Storage for localStorage, sessionStorage, or cookies.
  4. Find the value your app uses for authenticated requests.
  5. If the stored value already includes Bearer , use No prefix.
  6. If the stored value is just the raw token, use Bearer.

​
Common mappings

What your app storesWhere to configure itSourceKeySent as
raw JWT tokenauth sectionlocalStorageaccess_tokenAuthorization: Bearer <token>
full Bearer ... stringauth sectionlocalStorageauth_headerAuthorization: <stored value>
session cookie authauth sectionbrowser cookiesno keybrowser-managed cookies on credentialed requests
tenant or workspace idcustom headerscookiestenant_idx-tenant-id: <cookie value>

Auth cookies used through Send browser cookies with requests can be HttpOnly, because the browser sends them automatically on credentialed requests. Explicit cookie-to-header mappings still require a JavaScript-readable cookie value from document.cookie.

Use the cookie toggle when your app already authenticates browser requests with cookies. Use an explicit cookie-to-header mapping only when your API expects a separate header value such as tenant or workspace context.

​
Cross-origin note

Warpy executes backend tool requests from the browser, not from a hidden server-side proxy. The configured base URL must be reachable from the user’s browser and compatible with your CORS and auth setup. For cookie auth, your API must allow credentialed browser requests. For the first launch:
  • add local and production
  • configure auth
  • add MCP connections only if you need live MCP tools
  • verify one backend tool manually
  • only then continue to Features and tools