Endpoint and authentication
Account MCP (OAuth, Claude, browser connectors): one URL for your Amber account. Tools take abrand argument (slug) for each call.
{brand} with your brand slug. Use the same API key as REST on the
brand URL:
401 with
invalid_token. Missing credentials never fall back to an Amber login session.
The transport accepts POST only. There is no long-lived MCP session, SSE
subscription, or GET stream on this URL.
If you send an Origin header, it must exactly match https://app.amber.ai.
Other origins receive 403 before your key is checked. Server-side clients
usually omit Origin.
Request and per-key rate limits match the Authentication
guide, including 429 and Retry-After. Product include on
read_parent_products shares the same expansion credit bucket as REST.
Connect with the MCP TypeScript SDK
The examples use version 2.x of@modelcontextprotocol/client with Streamable
HTTP transport.
Set AMBER_API_KEY and AMBER_BRAND in a server environment. Do not embed
keys in browser bundles or paste them into model-visible tool arguments.
connect, use listTools to discover available tools and callTool
to read your data.
Tool names and paging
Tools mirror the public REST inventory:
Use
list_parent_products to find Parent Products and list_quotes to find
Quotes. Call listTools for the complete tool list and each tool’s parameters.
List results include items, nextCursor, and totalItems, plus a
collection object with the tool name and arguments to call again (without a
cursor). When nextCursor is not null, call the same list tool with that
cursor value. Default limit is 25; maximum is 100.
Detail results use { data, related }. Large child sets (SKUs, order lines,
quote revisions, supplier contacts) appear as bounded pages under related, each
with its own collection continuation. Follow those tools instead of expecting
unbounded arrays on data.
Read a Parent Product and walk SKUs
include on read_parent_products accepts the same comma-separated
collection names as REST product detail (for example skus,productOptions).
Each distinct include consumes expansion credits described in
Product graphs.
Tool responses are limited to 256 KiB. If a result is too large, the error
explains how to request less data. Reduce limit or request fewer included
collections, then follow pagination to retrieve the rest.
Restore API-key access
If a request returns401, check that the key is active and authorized for the
brand in your MCP URL. If the key was revoked or expired, ask your administrator
for a replacement and update your client configuration.
Connecting by client type
OAuth connection (browser consent)
OAuth is for clients that discover Amber through protected-resource metadata and complete browser consent. Sign in to Amber when prompted; your session proves which brands you may read. OAuth tokens work only with the account MCP URL.Connect an OAuth client
- Add the account MCP URL (
https://app.amber.ai/api/public/mcp) in your client and start the connection. The client opens Amber’s approval page. - Sign in if needed. Review the request and choose Allow or Cancel.
- Return to your client. Call
list_accessible_brands, then passbrandon other read tools for each brand you want to query. - Revoke the OAuth connection independently of API keys when you disconnect the app.
list_accessible_brands returns the brands you belong to. A system admin who
has verified admin MFA when they choose Allow gets access to all brands
instead. Amber records this access at consent, and it lasts for the life of the
grant. If you lose the system admin role, the grant falls back to the brands you
belong to.
If you are building an OAuth client, use the discovery, registration, and token
endpoints below. Your client handles these steps on behalf of its users.
Discovery
Fetch protected-resource metadata for the account MCP URL:Authorize and consent
Send the user through the authorization endpoint with S256 PKCE and an exactresource URL matching the account MCP endpoint
(https://app.amber.ai/api/public/mcp). Amber redirects to
/mcp-connect.html?request=<id> where the signed-in user approves or cancels.
Exchange the authorization code at POST /api/public/mcp/oauth/token with
grant_type=authorization_code, then call MCP with Authorization: Bearer <access_token> (not amb_sk_).
Refresh with grant_type=refresh_token on the same token endpoint. Disconnect
one client with POST /api/public/mcp/oauth/revoke using the client id and
access or refresh token. Revoking OAuth does not revoke API keys or other
clients’ grants.
OAuth limits
OAuth endpoints use IP-based rate limits and return429 with Retry-After when
exhausted. Access tokens expire within 15 minutes; grants expire within 30 days
of consent unless revoked earlier.
Claude remote connector
Use OAuth, not a long-lived API key in Claude’s connector settings.- In Claude, add a remote MCP connector that supports OAuth 2.1 discovery (or
enter Amber’s authorization-server metadata URL:
https://app.amber.ai/.well-known/oauth-authorization-server). - Point the connector at the account MCP resource (from protected-resource
metadata for
https://app.amber.ai/api/public/mcp). - When Claude opens Amber’s consent page, sign in if prompted, review the request, and choose Allow.
- After redirect, Claude exchanges the code and uses the OAuth access token on
https://app.amber.ai/api/public/mcp. Calllist_accessible_brands, then passbrandon read tools.
Disconnect one OAuth client
To remove a single MCP connection without revoking your API keys or other clients:401. Creating a
new authorization flow issues a new grant; other clients and keys are unchanged.
