Model Context Protocol (MCP)

Connect read-only MCP clients with your existing API key

Use Amber’s MCP server to read the same public business data as the REST API through typed tools. Every tool is read-only. Credentials stay in HTTP headers, never in tool arguments or URLs.

This guide covers API key connections for clients that send a Authorization header. Browser OAuth (for example Claude’s remote connector flow) is not available yet. When OAuth ships, this page will document discovery, consent, and independent grant lifecycle separately from API keys.

Endpoint and authentication

Each brand has its own MCP URL:

https://app.amber.ai/api/public/mcp/brands/{brand}

Replace {brand} with your brand slug. Use the same API key as REST:

Authorization: Bearer amb_sk_<prefix>_<secret>

Global keys must use a URL for the brand you intend to read. Brand-scoped keys must match that slug. Revoked, expired, or wrong-brand keys return 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 @modelcontextprotocol/client against Streamable HTTP. Install the same major versions Amber’s API tests use (2.x as of this writing).

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.

import { Client } from "@modelcontextprotocol/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const brand = process.env.AMBER_BRAND;
const origin = "https://app.amber.ai";
const url = `${origin}/api/public/mcp/brands/${encodeURIComponent(brand)}`;

const transport = new StreamableHTTPClientTransport(new URL(url), {
  requestInit: {
    headers: {
      Authorization: `Bearer ${process.env.AMBER_API_KEY}`,
      Accept: "application/json, text/event-stream",
    },
  },
});

const client = new Client({ name: "my-integration", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((tool) => tool.name).slice(0, 5));

await client.close();

After connect, call listTools and callTool. Initialization does not create a persistent session id on Amber’s server.

Tool names and paging

Tools mirror the public REST inventory:

Pattern	Example	Purpose
list_<collection>	list_parent_products	Filtered page of records
read_<collection>	read_parent_products	One record plus bounded related pages
Content	read_document_content, read_image_content	Binary or text payloads

REST path products becomes parent_products in tool names. REST rfqs maps to quotes tools. Hyphens in path segments become underscores.

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

const read = await client.callTool({
  name: "read_parent_products",
  arguments: { id: "00000000-0000-4000-8000-000000000001" },
});
const structured = read.structuredContent;
const skusPage = structured.related?.skus;
if (skusPage?.nextCursor) {
  await client.callTool({
    name: "list_skus",
    arguments: {
      ...skusPage.collection.arguments,
      cursor: skusPage.nextCursor,
    },
  });
}

Optional 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.

Each successful tool payload must fit within Amber’s MCP byte budget (256 KiB). Oversized graphs return a structured error with a narrower retrieval hint instead of silent truncation.

Verify a revoked key

Revoke the key in Amber settings, then repeat connect or any tool call. Amber returns 401 with the same body shape as REST key failures. Restore access by creating or rotating a key through your administrator.

Client compatibility

Client	Configuration	Status
MCP TypeScript SDK (Streamable HTTP)	API key in Authorization	Verified in Amber CI (public-mcp.test.ts, integration tests on merge)
Custom server integrations	Header-capable HTTP client	Verified (same transport and guards as SDK tests)
Claude remote connector	OAuth discovery and browser consent	Not available until Amber ships the OAuth MCP slice
Grok Bot apps	Vendor-specific MCP setup	Not verified (no recorded end-to-end run against this server)

Protocol SDK tests in CI do not substitute for a recorded Claude or Grok Bot session. Amber will update this table when OAuth and external client runs are completed.

OAuth (planned)

A future release will add OAuth protected-resource metadata, dynamic client registration, browser consent at /mcp-connect.html, token exchange, refresh, and per-client revocation without revoking your API keys. OAuth credentials will not call REST endpoints. Until that release ships, rely on API keys only for MCP.