gemstone-nexus · Phase 6

Atlas Vault — MCP Index B Integration (DOC02 Phase 2A)

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
6DOC-ATLAS-INDEX-BAtlas Vault — MCP Index B Integration (DOC02 Phase 2A)referenceDevResources/docs/DOC-Atlas-Index-B.mdGemStone is an **MCP client** to a remote Atlas Vault. This document describes the Index B contract GemStone speaks, how to point at a real vault, and the local stub used when no remote endpoint is configured.c9903bba6dc92e40d07693016d88d4ca2e96744d2026-11-18 16:51:43

Content

# Atlas Vault — MCP Index B Integration (DOC02 Phase 2A)

GemStone is an **MCP client** to a remote Atlas Vault. This document describes
the Index B contract GemStone speaks, how to point at a real vault, and the
local stub used when no remote endpoint is configured.

## Durable data model

See **[`DOC-Atlas-Data-Model.md`](./DOC-Atlas-Data-Model.md)** for Postgres
tables (`atlas_named_sessions`, `atlas_session_turns`,
`atlas_fine_tuning_signals`), Alembic `0008_atlas_vault`, and practitioner/org
segmentation via local JWT. Writers dual-write those tables even when this
remote Index B endpoint is still the stub.

## Status

- **Real remote Atlas Vault:** **DEFERRED on punchlist** (`DOC07-Punchlist.md`).
  Re-checked `DATARIGHT_DEV_SECRETS` 2026-07-21: 21 keys, **no** `ATLAS_*`
  (`ATLAS_MCP_ENDPOINT` / `ATLAS_MCP_API_KEY` absent). Phase 2A gates run
  against the in-process stub vault; stub does **not** block engineering.
- **Exact human ask:** add `ATLAS_MCP_ENDPOINT`, `ATLAS_MCP_API_KEY` (optional
  Bearer), optionally `ATLAS_MCP_MODE=auto` to `DATARIGHT_DEV_SECRETS`
  (us-east-1), then tell the agent secrets are ready for EC2 `.env` wire +
  `docker compose up -d --force-recreate api` + `/mcp/atlas/health` not stub.
- **Production path:** set env (or secrets) and restart `gemstone-api`.

## Environment

| Variable | Purpose | Default |
| --- | --- | --- |
| `ATLAS_MCP_ENDPOINT` | Base URL of Atlas Vault (no trailing slash), e.g. `https://atlas.example.com` | empty → stub |
| `ATLAS_MCP_API_KEY` | Optional Bearer token | empty |
| `ATLAS_MCP_MODE` | `auto` \| `stub` \| `remote` | `auto` |
| `ATLAS_STUB_DB` | SQLite path for stub vault | `$GEMSTONE_DATA_DIR/atlas_stub.db` |
| `ATLAS_QUERY_TIMEOUT_S` | HTTP timeout for remote Index B | `5` |

Store secrets in AWS Secrets Manager (`APP_SECRETS_ARN` or
`DATARIGHT_DEV_SECRETS`) — never commit them.

### Pointing at a real vault

```bash
# on EC2 / in .env (values from secrets manager)
ATLAS_MCP_ENDPOINT=https://<atlas-host>
ATLAS_MCP_API_KEY=<token>
ATLAS_MCP_MODE=auto
docker compose up -d --force-recreate api
curl -sf http://127.0.0.1:8000/mcp/atlas/health
```

When the remote is unreachable, the client **falls back to stub** for query /
signal / index / recall so voice sessions degrade gracefully.

## Index B HTTP contract (remote vault)

Relative to `ATLAS_MCP_ENDPOINT`:

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/mcp/index-b/health` | Health (fallback: `/mcp/health`) |
| POST | `/mcp/index-b/query` | Context retrieval |
| POST | `/mcp/index-b/signal` | Fine-tuning signal write |
| POST | `/mcp/index-b/index` | Upsert session summary for recall |
| POST | `/mcp/index-b/recall` | Named/dated session recall |

Compatibility fallbacks (prior StackOne-style ledger MCP):

- Query → `POST /mcp/query` `{ "question": "..." }`
- Signal / index → `POST /mcp/write` into `ContextIndex`

### Query body

```json
{
  "practitioner_id": "uuid",
  "org_id": "uuid",
  "query": "vendor contract terms",
  "limit": 8,
  "session_id": "optional"
}
```

### Signal body

```json
{
  "practitioner_id": "uuid",
  "org_id": "uuid",
  "session_id": "optional",
  "signal_type": "correction|rating|explicit_feedback",
  "original_text": "...",
  "corrected_text": "...",
  "rating": 4,
  "context": "optional",
  "metadata": {}
}
```

### Recall body

```json
{
  "practitioner_id": "uuid",
  "org_id": "uuid",
  "query": "the conversation from last Tuesday about the vendor contract",
  "limit": 5
}
```

## GemStone proxy routes

GemStone exposes the same surface for UI / Capacitor (and Swagger):

- `GET  /mcp/atlas/health`  (also `/api/v1/atlas/health`)
- `POST /mcp/atlas/query`
- `POST /mcp/atlas/signal`
- `POST /mcp/atlas/recall`
- `POST /mcp/atlas/index`
- `POST /mcp/gemstone/correction` — practitioner correction → signal writer

WebSocket session protocol additions:

- Client `{"type":"recall","query":"..."}` → server `recall_result`
- Turns / end auto-index the session into Atlas for later recall

## Gates

```bash
make phase2a-gates
# or
bash scripts/phase2a-gates.sh
```

Exit criteria (DOC02 §6.4):

1. Index B context queries p95 ≤ 800ms under 50 concurrent practitioners
2. Fine-tuning signal verifiably written within 2s of correction
3. Named/dated recall correct in ≥ 9/10 cases

## Stub vs real vault

The stub is **gate scaffolding**, not an embedded production Atlas Vault
(DOC06). It persists to `ATLAS_STUB_DB` so soak/restart still exercise recall
and signal verification. Replace it by configuring `ATLAS_MCP_ENDPOINT`.