Skip to main content

Structured Data

Store and query JSON documents with metadata.

Data Model​

{
  namespace: string      // Logical grouping
  key: string           // Unique identifier
  data: object          // JSON document
  metadata: object      // Queryable attributes
  version: number       // Version number (auto-incremented)
  is_active: boolean    // Latest version flag
}

Operations​

Called as tools through your MCP client — the examples below show the tool name and arguments; how you invoke them depends on your framework.

Save​

Create or update an entry:

{
  "tool": "structured_data_save",
  "args": {
    "namespace": "products",
    "key": "product:laptop-123",
    "data": {
      "name": "Pro Laptop",
      "price": 1299,
      "specs": {"ram": "16GB", "cpu": "M1"}
    },
    "metadata": {
      "category": "electronics",
      "brand": "Apple",
      "in_stock": true
    }
  }
}

Creates a new version; the previous version remains in history.

Get​

Fetch by key:

{
  "tool": "structured_data_get",
  "args": { "namespace": "products", "key": "product:laptop-123" }
}

Returns the latest active version by default. Pass "version": 1 to fetch a specific historical version.

Query​

Search by metadata filters:

{
  "tool": "structured_data_query",
  "args": {
    "namespace": "products",
    "filters": {
      "metadata.category": "electronics",
      "metadata.brand": "Apple",
      "metadata.in_stock": true
    }
  }
}

Returns an array of matching entries, each with namespace, key, data, metadata, and version.

Versioning​

Every update creates a new version:

VersionDatais_active
1{"price": 1299}false
2{"price": 1199}false
3{"price": 999}true

Get always returns latest active unless version specified.

Key Patterns​

Recommended patterns:

  • Entity:ID: user:123, order:abc
  • Hierarchical: config:app:theme, config:app:lang
  • Timestamped: log:2026-07-10:001

Metadata Best Practices​

Use metadata for queryable attributes:

{
  "metadata": {
    "type": "user",           # Entity type
    "status": "active",       # Status
    "region": "us-west",      # Geographic
    "created_at": "2026-07-10",
    "tags": ["premium", "verified"]
  }
}

Query by these attributes efficiently.

Knowledge Scope​

Agents need permission to access namespaces:

{
  "structured_data_namespaces": {
    "products": {
      "keys": ["*"],
      "permission": "read_write"
    }
  }
}

Wildcards:

  • ["*"] - All keys
  • ["product:*"] - Keys starting with product:
  • ["config:*", "user:*"] - Multiple patterns

Next Steps​