External Record Store

Keep records from your other systems inside AVstackr — scoped to your tenant, retrieved via MCP. Your CRM tickets, field-service visits, site notes, or anything else that lives in JSON can live here too.

Screenshot — namespaces table

External Records section in Global Project Configuration with 1–2 namespaces registered. Columns: Name / Display Name / Records / Created / Actions.

Drop file to fill: wwwroot/Images/docs/external_record_store_namespaces_table.png

Where you register and manage namespaces — inside Global Project Configuration.

What it is

The External Record Store is a key-value store built into AVstackr. You push JSON records in, fetch them back by ID, or pull everything updated since a watermark. AVstackr stores the data verbatim — it doesn't interpret what's inside the payload until you author a mapping (Stage 2, not yet shipped).

Records are organized into namespaces — buckets you register ahead of time. A namespace is just a name like site_visits or service_tickets. Every record belongs to one namespace and has your own key (external_id) so you can refer to it the same way your source system does.

When to use it

• Your CRM has customer or ticket data you want accessible when an AI agent is working in AVstackr via MCP.
• Your field-service tool tracks site visits you want to keep close to AVstackr projects.
• You have a flat key-value record store need and the data lives in JSON — no heavyweight database required.
• You want an AI agent to be able to look something up across two systems in one conversation.

What it is not

• Not a search index. Query returns records by update time, not by content. Full-text or semantic search over payloads isn't supported.
• Not a file store. Don't put file bytes in payloads. Binary data belongs in object storage. Payloads are capped at 64 KB.
• Not a database with history. Writing a record with an existing external_id overwrites the previous value. There's no revision log.
• Not reversible. Deletes are hard. If you delete a record, recovery is from your source system — not from AVstackr.

The three things

1. Namespaces

A namespace is a bucket that belongs to your tenant. You register it once in Global Project Configuration → External Records, then push records into it. Names are immutable — once registered, you can't rename a namespace (you'd create a new one and migrate). Pick something meaningful: service_tickets, site_visits, crm_contacts.

Screenshot — Register Namespace modal

Modal open with Name = site_visits and Display Name = Site Visits. Validation hint visible under the Name field.

Drop file to fill: wwwroot/Images/docs/external_record_store_register_modal.png

The Name field is the address used in MCP calls and can't be renamed later. The Display name is editable.

2. Records

Each record is a JSON object stored under a namespace + your own external_id. Writing the same external_id again is an idempotent upsert — the payload is replaced, updated_at is bumped, nothing else changes. Push as often as your source system changes; there's no extra cost for upserts.

3. Retrieval

Three ways to get records back out:

• By ID — call external_records_get with the namespace and your external_id. Returns the record or record_not_found.
• By watermark — call external_records_query with a since timestamp. Returns every record in the namespace updated after that moment, up to the server page ceiling. Use the returned next_since value as your next watermark to pick up where you left off.
• Discover namespaces — call external_records_list_namespaces to see what's registered. Useful when an AI agent is connecting for the first time and doesn't already know the namespace names.

Getting started

1. Open Global Project Configuration and navigate to the External Records section. Register a namespace — name it something like site_visits. The name can't be changed after registration, so choose deliberately.
2. From your MCP client (Claude Desktop, a custom agent, etc.), call external_records_put with the namespace name, your record's ID, and the JSON payload. First write creates the record; subsequent writes with the same ID update it.
3. Later, call external_records_get to fetch a specific record by ID, or external_records_query with a since timestamp to pull everything that's changed since your last sync.

Screenshot — External Records Console

Console modal (opened from Global Project Configuration → External Records → Open Console) after a successful external_records_put. Inputs on the left, JSON response + latency badge on the right.

Drop file to fill: wwwroot/Images/docs/external_record_store_console_success.png

The Open Console button in Global Project Configuration → External Records lets admins invoke the five MCP tools end-to-end without an external client. Read-only users see only the read tools.

Guardrails

• 64 KB payload cap — each record's JSON payload must be under 65,536 bytes. The API returns payload_too_large if you exceed it.
• 60 writes per minute per tenant — sustained writes beyond this rate are rejected with rate_limited and a retry_after_seconds hint.
• Hard server page ceiling on query — external_records_query never returns more than the server limit per call. Paginate with the returned next_since.
• Hard delete only — external_records_delete removes the record permanently. There's no soft delete, no undelete, and no trash. Your source system is the recovery path.

What's coming in Stage 2

Today, AVstackr stores the payload but doesn't interpret it. A later release will let you author a mapping — a definition that tells AVstackr how to connect a record to an AVstackr concept. Once a mapping exists, a service ticket could appear in the project view, or a webhook could fire when a record is written. That's Stage 2; it hasn't shipped yet.