scintilla-mcp-server

Scintilla MCP

A small, self-hosted Model Context Protocol server that gives AI assistants (Claude, and any other MCP client) read-only access to your organization's Walmart Scintilla BI Link data.

BI Link is a Google BigQuery share: Walmart Data Ventures gives each supplier a service-account key and a dataset (wmt-dv-bi-link-prod.dv_supplier) of ~54 views covering store sales, inventory and in-stock, demand and order forecasts, out-of-stock root cause, returns, modular placement, item and store dimensions. This server sits in front of that share so your team can ask questions in plain English while the key stays on the server.

Not affiliated with, endorsed by, or supported by Walmart Inc. or Walmart Data Ventures. You need your own BI Link subscription and service-account key.

What you get

Tool	Purpose
scintilla_list_views	Every view in the share, with a one-line description and last refresh time
scintilla_describe_view	Columns, types and 3 sample rows for one view
scintilla_query	Read-only SQL: SELECT/WITH only, single statement, dv_supplier only, automatic LIMIT
scintilla_find_items	Look up Walmart item numbers, UPCs, names, brand and category
scintilla_sales_summary	This year vs last year sales, units, AUR and store counts by item, category, brand, channel, week, region or total
scintilla_inventory_snapshot	Latest on-hand, on-order, in-transit, replenishment in-stock % and zero-on-hand stores by item
scintilla_oos_root_cause	Walmart's out-of-stock attribution (Supplier, Store Ops, Forecast, Modular, Other) by reason, item or month
scintilla_demand_forecast	Store demand forecast summed by item and week
scintilla_item_store_detail	Store-level sales and in-stock for one item, worst in-stock first

Guardrails: SQL is limited to SELECT against the BI Link dataset (DDL/DML keywords and other projects are rejected), results are capped (MAX_ROWS, default 500), queries time out (QUERY_TIMEOUT_S, default 90), and every request needs the bearer token. The service account Walmart issues is itself read-only, so there is no write path at any layer.

How it works

Claude / MCP client  --HTTPS, bearer token-->  Scintilla MCP (this repo)  --service account-->  BigQuery (Walmart's share)

The server speaks MCP over Streamable HTTP (stateless, JSON responses) and runs anywhere a container runs. Query cost is billed to Walmart's project under the BI Link terms; the views scan the full shared tables even for small aggregates, so per-query byte caps are off by default.

Quick start (local)

git clone https://github.com/<you>/scintilla-mcp-server.git
cd scintilla-mcp-server
cp .env.example .env            # fill in GCP_SERVICE_ACCOUNT_JSON and MCP_BEARER_TOKEN
docker compose up --build

Then:

curl -s localhost:8080/health          # -> ok
curl -s -X POST localhost:8080/mcp/$MCP_BEARER_TOKEN \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Without Docker: pip install -r requirements.txt, export the env vars, python -m scintilla_mcp.server.

Configuration

Variable	Required	Default	Notes
GCP_SERVICE_ACCOUNT_JSON	yes		The full JSON key Walmart Data Ventures issued (svc-wmt-dv-...@wmt-dv-bi-link-prod.iam.gserviceaccount.com). Paste the whole file as one value.
MCP_BEARER_TOKEN	yes		Long random secret. openssl rand -hex 32.
BQ_PROJECT	no	wmt-dv-bi-link-prod	Only change if Walmart tells you to.
BQ_DATASET	no	dv_supplier	Only change if Walmart tells you to.
VENDOR_NBRS	no		Comma-separated Walmart vendor numbers to restrict item lookups to (trims legacy vendor records).
MAX_ROWS	no	500	Row cap per tool call.
QUERY_TIMEOUT_S	no	90	BigQuery job timeout.
MAX_BYTES_BILLED	no	0 (off)	Per-query byte cap. Leave off unless you pay for the queries.
ALLOWED_HOSTS	no		Comma-separated hostnames to re-enable the SDK's Host-header check. Off by default because the server sits behind a reverse proxy and is gated by the token.
HC_PING_URL	no		Healthchecks.io ping URL. Enables a heartbeat every HEARTBEAT_INTERVAL_S (600) that probes BigQuery and pings ok or /fail.
AXIOM_TOKEN, AXIOM_DATASET, AXIOM_AGENT_ID	no	agent-runs, scintilla-mcp	Axiom ingest. Heartbeats and each tool call are written as started / finished / failed events.
PORT	no	8080

Authentication

Every MCP request must carry the shared token, in one of two forms:

• Authorization: Bearer <token> (Claude Desktop, Claude Code, Cursor, any client that can set headers)
• The last path segment: https://<host>/mcp/<token> (claude.ai organization and custom connectors, which cannot set headers)

Requests without a valid token get 401. OAuth discovery paths return 404 on purpose so claude.ai does not attempt OAuth client registration. If you need per-user identity, put an OAuth-aware proxy in front (Cloudflare Access, Entra, etc.) and keep this token as the service-to-service secret.

Deploying

Any platform that runs a Docker image and terminates TLS works. Included:

• DigitalOcean App Platform: .do/app.yaml (edit the repo name, set the two secrets). About $5/month.
• Docker Compose: docker-compose.yml for a VM or on-prem box behind your own reverse proxy.

Also tested patterns: Fly.io (fly launch on the Dockerfile), Google Cloud Run (gcloud run deploy --source .), Azure Container Apps, Render. The container listens on PORT and exposes GET /health for probes.

Connecting a client

claude.ai (organization or personal custom connector): Settings → Connectors → Add custom connector. Name it (for example Scintilla MCP), URL https://<host>/mcp/<MCP_BEARER_TOKEN>, no OAuth. Members then enable it under their own Connectors settings.

Claude Desktop / Claude Code / other MCP clients (mcp.json):

{
  "mcpServers": {
    "scintilla": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <MCP_BEARER_TOKEN>" }
    }
  }
}

First things to ask: "List the Scintilla views." · "Sales by category, last 4 weeks vs last year." · "Which items have the worst in-stock right now?" · "What is Walmart attributing our out-of-stocks to this month?"

Notes on the data

• ty_* columns are this year, ly_* the same period last year as Walmart aligns it. Dollars are retail.
• store_sales covers Walmart US stores plus store-fulfilled online (svc_chnl_nm: BIS in-store, PICKUP, DELIVERY, SFS, S2H). Marketplace and Sam's Club are not in BI Link.
• The share is a rolling 52 weeks. If you need history, land the views in your own warehouse on a schedule.
• store_invt and hourly_store_inventory are tens of millions of rows; aggregate in SQL, never pull raw store-item-days through the model.

Development

pip install -r requirements.txt -r requirements-dev.txt
pytest

Tests cover the SQL guard and auth middleware without touching BigQuery.

License

MIT. See LICENSE.