Watt Data

MCP Resources let AI assistants read uploaded CSVs and workflow artifacts through the workflow:// URI scheme, and browse trait metadata through the trait:// URI scheme.

URI Format

workflow://{workflow_id}/{type}/{filename}
  • uploads/ — Files you uploaded via generate_upload_url
  • artifacts/ — Outputs generated by workflow tools (JSON, CSV, or Parquet)

Example:

workflow://550e8400-e29b-41d4-a716-446655440000/uploads/customers.csv

Listing Resources

Use resources/list with the workflow ID as cursor to discover all files in a workflow.

{ "method": "resources/list", "params": { "cursor": "550e8400-..." } }

Reading Resources

Use resources/read with a workflow:// URI.

{ "method": "resources/read", "params": { "uri": "workflow://550e8400-.../uploads/customers.csv" } }

CSV Sampling

Append query parameters to sample large CSVs without loading the entire file:

workflow://.../uploads/customers.csv?offset=0&limit=10
ParameterDefaultDescription
offset0Starting row (0-indexed)
limit10Max rows to return
formatcsvOutput format: csv, json, or jsonl

Artifact Format Selection

Access artifacts in different formats by changing the file extension:

workflow://.../artifacts/resolved_identities.json
workflow://.../artifacts/resolved_identities.csv
workflow://.../artifacts/resolved_identities.parquet

Parquet URIs return a presigned download URL. CSV and JSON artifacts also support sampling query parameters.

Trait Resources

Browse trait metadata via the trait:// URI scheme. These resources replaced the former trait_list tool.

Available Resources

URIDescription
trait://personBrowse person trait metadata
trait://businessBrowse business trait metadata

Reading Traits

Use resources/read with a trait:// URI:

{ "method": "resources/read", "params": { "uri": "trait://person" } }

Returns JSON with trait metadata (trait_id, trait_hash, name, value, domain, size, prevalence) and pagination info.

Query Parameters

Append query parameters to filter and paginate:

trait://person?domain=demographic,interest&limit=20&offset=40
ParameterDefaultMaxDescription
domainall-Comma-separated domain filter
trait_name--Filters to the row's name field — works across all domains, e.g. trait_name=state for geo or trait_name=has_home_business for lifestyle
limit50200Max traits to return
offset0-Number of traits to skip

Mixing domain=geo with non-geo domains in a single read is not supported (geo entries come from a separate backing store and pagination would be ambiguous). Issue two reads — one with ?domain=geo, one with the other domains.

Response Format

{
  "entity_type": "person",
  "traits": [
    {
      "trait_id": "1000000001",
      "trait_hash": "abc123",
      "name": "golf_affinity",
      "value": "high",
      "domain": "affinity",
      "size": 1500000,
      "prevalence": 0.05
    }
  ],
  "total": 5000,
  "returned": 50,
  "has_more": true,
  "next_offset": 50
}

Available trait domains are surfaced statically on consuming tool schemas (e.g. the domains parameter on trait_search / entity_find).

Geographic Boundaries

trait://person?domain=geo browses the synthetic geo catalog populated from the spatial-boundary index. Use trait_name=<boundary_type> to scope the read to a single boundary type. Geo applies to entity_type: "person" only.

trait_name (boundary type)value formatExample
stateUSPS two-letter code"CA"
zip55-digit ZIP code"94103"
countyCounty name as stored"Los Angeles"
dmaNielsen DMA numeric ID"506"
cbsa5-digit OMB code"10100"
msa2-4 digit OMB code"1000"
congressional_districtTwo-digit district number (today; state-prefixed after a planned upstream rebuild)"12"

Example: browse all states

{ "method": "resources/read", "params": { "uri": "trait://person?domain=geo&trait_name=state&limit=60" } }

Returns 53 rows (50 states + DC + populated territories present in the boundary index) with has_more: false.

Example: paginate within a boundary type

{ "method": "resources/read", "params": { "uri": "trait://person?domain=geo&trait_name=state&offset=50&limit=10" } }

Returns the final 3 rows with has_more: false.

For known boundary values, use trait_get with domain="geo", trait_name=<type>, trait_value=<value> — that's the fastest path when you already know the boundary (state, ZIP, DMA, etc.). The browse path is for discovery and pagination.

County and congressional_district caveats. County values are bare names without a state qualifier, and (until upstream rematerialisation) congressional districts are bare two-digit numbers ambiguous across states. Full detail and workarounds: see entity_find.


Related:

On this page