Build with Clear Tools and Honest Boundaries.

Overview

Two interfaces exist today, both public and both honest about their limits:

Tool discovery

MCP clients start by listing tools. Each tool advertises a name, a description, a JSON Schema for its inputs and a read-only hint. KEYXE’s catalog is published as a static file so you can inspect it without running anything.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Download tool catalog (JSON)

Query safety

• No free-form SQL. Datasets, metrics and groupings come from allow-lists.
• Every argument is validated against a schema; unknown fields are rejected.
• Date ranges must fall inside data coverage; future dates are rejected.
• Results are limited (at most 100 grouped rows per call).
• Errors are structured: INVALID_ARGUMENT, UNSUPPORTED_METRIC, UNSUPPORTED_GROUPING, INVALID_DATE_RANGE, NOT_FOUND.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "analytics_query",
    "arguments": {
      "dataset": "sample_seller_sales_daily",
      "metrics": ["units", "sales"],
      "group_by": "category",
      "marketplace": "UK",
      "date_range": { "preset": "30d" },
      "limit": 5
    }
  }
}

Schema conventions

Every tool response wraps its result in an envelope that carries provenance, so downstream consumers — people or AI clients — cannot mistake synthetic, stale or partial data for something else.

{
  "mode": "synthetic_demo",
  "tool": "analytics_query",
  "request_id": "demo-req-000002",
  "source": "keyxe_synthetic_fixtures",
  "org_bound": "demo-org (fictional)",
  "marketplace": "UK",
  "currency": "GBP",
  "as_of": "2026-10-01T00:00:00Z",
  "units": "Money in major units of the marketplace currency; ratios as decimals",
  "attribution": null,
  "is_live_amazon_data": false,
  "warnings": ["Synthetic sample data. No Amazon API call was made."],
  "result": { "group_by": "category", "rows": ["…"], "row_count": 5 }
}

Samples

The simulator is plain TypeScript with no network access. This example mirrors what the in-browser explorer does.

// Offline example: runs the same browser-local simulator used by keyxe.net/demo.
// No network calls; every result is synthetic.
import { McpSimulator } from '@keyxe/synthetic-data/mcp';

const sim = new McpSimulator();
const res = sim.call('analytics_query', {
  dataset: 'sample_ads_campaign_daily',
  metrics: ['spend', 'attributed_sales', 'acos'],
  group_by: 'format',
  marketplace: 'US',
  date_range: { preset: '90d' },
});

const out = res.result.structuredContent;
console.log(out.is_live_amazon_data); // false
console.log(out.warnings[0]);         // "Synthetic sample data. No Amazon API call was made."
console.table((out.result as { rows: unknown[] }).rows);

Download synthetic sample data (JSON)

The @keyxe/synthetic-data package is part of the private KEYXE repository today and is a candidate for open-source release after review. See Open Source.

Permission model

Developer access never substitutes for Amazon authorization. In production, three separate checks apply: who the user is (KEYXE sign-in), what KEYXE may read for their organization (separate seller and advertising authorizations from Amazon), and what an AI client may call (scoped MCP authorization plus data-use policy).

Open source

Tool schemas, synthetic fixtures and these examples are the first candidates for a public release. No public repository exists yet; when one does, it will be linked here.

Read the open-source plan