# VisualGrid MCP Protocol

This file is published to <a href="https://mcp.g3nretailstack.com/visualgrid/PROTOCOL.md" target="_blank" rel="noopener noreferrer">https://mcp.g3nretailstack.com/visualgrid/PROTOCOL.md</a>.


## Usage patterns (headless)
- Stack-wide SOPs & operations catalog: <a href="https://doc.g3nretailstack.com/story/operations.html" target="_blank" rel="noopener noreferrer">/story/operations.html</a>.
- Super-usecase scenarios + QA status: <a href="https://doc.g3nretailstack.com/story/super-usecases.html" target="_blank" rel="noopener noreferrer">/story/super-usecases.html</a>.
- This protocol stays contract-only; use the catalogs for workflow expectations.

## Base URL
- API Gateway: `https://api.g3nretailstack.com/visualgrid`
- Health check: `GET /visualgrid/ping` — no auth required.

## Auth + tenancy
- VisualGrid uses a custom root-token auth model, not the standard `x-session-guid` / `x-api-key` pattern.
- Obtain a token via `POST /visualgrid/root/auth` with `secret_code` (scrypt-validated against DDB hash).
- Pass the token as `x-vg-token` header (or `vg_token` body field) on all root-protected routes.
- Tokens are short-lived (1h TTL).
- `/ping` and `/root/auth` require no authentication.
- All other routes require `root` auth mode.
- VisualGrid is not org-scoped; it provides cross-service read-only graph traversal of all 21 DDB tables.

## Roles
- Root: full access to all graph operations. Granted via `secret_code` authentication.
- No org-level roles. VisualGrid is an operator/platform tool.

## Surfaces
- Contract-only surface. Implemented and deployed; see `/visualgrid/openapi.yaml` for the current surface definition.

## Endpoint inventory (OpenAPI parity)
The endpoints below are implemented and defined in `/visualgrid/openapi.yaml`. Request/response schema names reference OpenAPI component schemas.

| Method | Path | Request schema | Response schema |
| --- | --- | --- | --- |
| GET | /ping | — | PingResponse |
| POST | /root/auth | RootAuthRequest | RootAuthResponse |
| GET | /root/graph | — | GraphEntryResponse |
| POST | /root/graph | — | GraphEntryResponse |
| POST | /node/load | NodeLoadRequest | NodeLoadResponse |
| POST | /node/children | NodeChildrenRequest | NodeChildrenResponse |
| POST | /node/export | NodeExportRequest | NodeExportResponse |
| POST | /node/history | (inline: table, pk, sk, limit?, next_token?) | (inline: items[], has_more, count) |
| GET | /schema | — | (inline: services[], edges[], entity_types[]) |

## Auth modes

| Mode | Mechanism | Description |
| --- | --- | --- |
| **root** | `x-vg-token` header | Short-lived token obtained via `/root/auth`. Full access to all 21 service tables. |
| **none** | No auth required | Public endpoints (ping, root/auth). |

## Data presentation
- Root-only access means no untrusted users -- all fields are returned unredacted.
- DDB keys (PK, SK, GSI1PK, GSI1SK, etc.) are extracted from the record and placed into a separate `ddb_keys` object. This keeps the `properties` object clean for display while preserving key information for navigation.

## Pagination
- Default limit: 25.
- Clamp: 1-256.
- Cursor: opaque `next_token` (base64-encoded DDB ExclusiveStartKey).
- Pass `next_token` from previous response to fetch next page.
- `null` or absent `next_token` in response indicates last page.

## Error tags
Common tags: `invalid-input`, `unauthorized`, `forbidden`, `not-found`, `internal-error`.

| Tag | HTTP Status | Description |
| --- | --- | --- |
| `invalid-input` | 400 | Missing or malformed request fields |
| `unauthorized` | 401 | Missing or invalid auth credentials |
| `forbidden` | 403 | Auth valid but insufficient access |
| `not-found` | 404 | Requested node/table does not exist |
| `internal-error` | 500 | Unexpected server error |

## Example envelopes
Success envelope (shape-only):
```json
{
  "ok": true,
  "data": { "node": { "ddb_keys": { "PK": "USER#u_abc", "SK": "USER#META" }, "properties": { "status": "verified" }, "metadata": { "service_code": "uas", "table": "uas_main" } } },
  "build": { "service": "visualgrid", "version": "1.0.0" }
}
```

Error envelope (shape-only):
```json
{
  "ok": false,
  "error": {
    "tag": "unauthorized",
    "message": "Invalid or expired root token"
  },
  "build": { "service": "visualgrid", "version": "1.0.0" }
}
```

## Idempotency & retries
- All endpoints are read-only and safe to retry with identical inputs.
- No mutations exist in the VisualGrid surface; there is no `expected_revision` pattern.
- The `/root/auth` endpoint is idempotent (same `secret_code` returns a new token each time, but the operation has no side effects beyond token creation).

## Known pitfalls
- **Token expiry**: Root tokens expire after 1 hour. On `401 unauthorized`, re-authenticate via `/root/auth`.
- **Table not in registry**: Requesting a table not in the service registry returns `404 not-found`. Valid tables are returned by `GET /root/graph`.
- **Pagination cursors**: `next_token` is opaque base64. Do not modify, decode, or persist cursors across sessions -- they may change format between deploys.

## OpenAPI
- Contract schema: <a href="https://doc.g3nretailstack.com/visualgrid/openapi.yaml" target="_blank" rel="noopener noreferrer">https://doc.g3nretailstack.com/visualgrid/openapi.yaml</a>
- Graph: root/auth, root/graph, schema.
- Node: node/load, node/children, node/export, node/history.
- Health: ping.


_Build MONDAY-1776194870 • 2026-04-14T19:27:50.000Z • [© 1999 Microhouse Systems Inc. All rights reserved.](https://doc.g3nretailstack.com/common/copyright-license.html)_