gemstone-nexus · Phase 6
Atlas Vault — MCP Index B Integration (DOC02 Phase 2A)
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 6 | DOC-ATLAS-INDEX-B | Atlas Vault — MCP Index B Integration (DOC02 Phase 2A) | reference | DevResources/docs/DOC-Atlas-Index-B.md | 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. | c9903bba6dc92e40d07693016d88d4ca2e96744d | 2026-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`.