Context retriever

Give an AI agent safe, structured access to the records in a KiviDB database: customers, orders, tickets, whatever your application keeps there. You describe the records once, as a context model; KiviDB builds the search indexes and gives agents a set of tools over them, through the Model Context Protocol (MCP) or plain HTTP. Instead of writing SQL or raw commands, the agent calls search_customer or customer_orders, and gets back only the fields you chose.

Each agent connects with its own agent key. A key can be limited to some of the model's entities and can carry fixed filters, such as customer.tenant = acme: every query through that key adds them, on the server, whatever the agent asks for. A record outside them is not found, exactly as if it did not exist.

A context model

A model belongs to one database and lists its entities. Each entity is:

Name and description	customer: "A customer account with its plan and monthly revenue." The agent reads the description to choose a tool.
Key prefix	every record is a key under it, such as customer:42
Stored as	hashes, or JSON documents
Id field	the field holding the record's id; it is indexed so records can be fetched by it
Fields	each one text (searched by words), tag (matched exactly: ids, statuses, tenants) or numeric (compared and ranged)
Related records	e.g. orders: the order records whose customer_id is this customer's id

The records can come from your application or from a data integration pipeline that keeps tables from PostgreSQL or MySQL in KiviDB.

KiviDB builds one search index per entity, kividb:ctx:<model>:<entity>, over the keys already under its prefix, and keeps it up to date as keys change. Saving the model again rebuilds them. Deleting the model drops the indexes and revokes its keys; the records themselves are never touched.

The tools

For every entity:

Tool	Does
search_<entity>	words in its text fields (query), exact values of its tag fields, <field>_min and <field>_max for its numeric fields; up to 50 records
get_<entity>	one record by id
<entity>_<relationship>	the related records of one record, e.g. customer_orders

Records come back with the id and the model's fields only. Any other field in the key (an internal note, a password hash) is never returned.

Agent keys

Make keys in the console (the model's Agent keys tab) or with the API. The key, which starts kvctx_, is shown once and stored only as a hash. Revoke a key at any time.

Connect an MCP client with:

{
  "mcpServers": {
    "kividb-support": {
      "type": "http",
      "url": "https://api.kividb.io/context/mcp",
      "headers": { "Authorization": "Bearer kvctx_..." }
    }
  }
}

An agent without MCP lists its tools with GET /context/tools and calls one with POST /context/tools/{tool} and a body of {"arguments": {...}}, with the same Authorization header. Each key may make 600 calls a minute.

In the console

The Context retriever section lists every model in your organization; each database also has a Context retriever tab. A model shows its entities with how many records each index holds, its tools with a place to run any of them, either seeing everything or exactly as one of its keys would, and its keys. Context models are not available on sharded databases yet.

API

Request
GET /context-models	every model in the organization
GET /instances/{id}/context-models	the models over one database
PUT /context-models/{name}	create or change a model: {"instance_id", "description", "entities": [...]}; its indexes are rebuilt
GET /context-models/{name}	the model, its tools, record counts and keys
DELETE /context-models/{name}	delete it and its indexes
POST /context-models/{name}/try	run a tool: {"tool", "arguments", "key_id"?}
POST /context-models/{name}/keys	make a key: {"name", "entities"?, "filters"?: {"customer": {"tenant": "acme"}}}
DELETE /context-models/{name}/keys/{keyId}	revoke a key

curl -X PUT https://api.kividb.io/context-models/support \
  -H "Authorization: Bearer $KIVIDB_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "instance_id": "'"$DB"'",
    "description": "Customers and their orders, for the support assistant.",
    "entities": [
      { "name": "customer", "description": "A customer account.", "prefix": "customer:", "storage": "hash", "id_field": "id",
        "fields": [ { "name": "name", "type": "text" }, { "name": "tenant", "type": "tag" }, { "name": "plan", "type": "tag" } ],
        "relationships": [ { "name": "orders", "entity": "order", "field": "customer_id" } ] },
      { "name": "order", "description": "An order a customer placed.", "prefix": "order:", "storage": "json", "id_field": "id",
        "fields": [ { "name": "customer_id", "type": "tag" }, { "name": "status", "type": "tag" }, { "name": "total", "type": "numeric" } ] }
    ]
  }'