MCP Server

Available in 3.x only (3.0.0-beta and later).

The MCP server (mcp-server module) exposes Yaci Store to AI agents over the Model Context Protocol . An agent connected to it can discover the analytics tables, read their schemas, run read-only SQL over the exported data (optionally reaching the chain tip through unified views), look up address balances, identify dApps and convert between Cardano units, slots and timestamps.

The analytics tools are a thin layer over the Query API: they use the same engine in-process, so SQL validation, row limits, timeouts and unified views behave exactly as described there.

Quick start

Activate the analytics and mcp profiles together. analytics runs the export that produces the data; mcp turns on the MCP server, the query layer and unified views.

Docker / zip distribution — edit config/env:

SPRING_PROFILES_ACTIVE=analytics,mcp

# or together with ledger-state
SPRING_PROFILES_ACTIVE=ledger-state,analytics,mcp

Jar:

java -jar yaci-store.jar --spring.profiles.active=analytics,mcp

Then point an MCP client at the endpoint:

http://localhost:8080/mcp

The analytics tools only return data once the first export partitions have completed; until then analytics-list-tables reports no tables. See Analytics Store for how the export catches up.

What the mcp profile enables

config/application-mcp.yml sets:

yaci:
  store:
    mcp-server:
      enabled: true                 # the MCP server and the /mcp endpoint
      dapp-registry:
        enabled: true
        external-registry:
          enabled: false            # no outbound sync of the CRFA dApp registry
      tools:
        external-metadata:
          enabled: true             # token registry / IPFS lookups (outbound HTTP)
 
    analytics:
      query:
        enabled: true               # query layer behind the analytics tools
        live-data-enabled: true     # unified views: exported history + live PostgreSQL
        rest-api-enabled: false     # REST query endpoints stay off

yaci.store.mcp-server.enabled is the only switch for the server itself. Without it, /mcp returns 404 and no tools are registered. The analytics tools additionally require yaci.store.analytics.query.enabled=true; if the query layer is off, the server still starts with the dApp, metadata and utility tools only.

Unified views

With live-data-enabled=true (the mcp profile default), each eligible table is a unified view: rows inside the exported range come from Parquet/DuckLake, rows after it come from your PostgreSQL database. A query such as SELECT count(*) FROM transaction WHERE epoch = <current epoch> therefore reaches the chain tip instead of stopping at the last completed export.

• analytics-list-tables reports a dataScope for every table: historical+live (reaches the tip) or historical (exported data only).

• Unified views need the PostgreSQL database Yaci Store syncs into; they add read load on it only for the live tail.

• To keep the tools on exported data only, override the profile:

  yaci.store.analytics.query.live-data-enabled=false

• To keep specific heavy tables historical, list them in yaci.store.analytics.query.live-data-excluded-tables.

How the exported range and the boundary are calculated is described in Query API & Unified Views.

Connecting a client

The server uses Spring AI’s streamable HTTP transport in stateless mode at /mcp.

Claude Code:

claude mcp add --transport http yaci-store http://localhost:8080/mcp

Clients that accept a server URL (for example Cursor’s mcp.json):

{
  "mcpServers": {
    "yaci-store": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Clients that only support stdio can connect through the mcp-remote bridge:

{
  "mcpServers": {
    "yaci-store": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

To inspect the tools by hand, run the MCP Inspector  (npx @modelcontextprotocol/inspector), choose the Streamable HTTP transport and enter the URL above.

Tools

Analytics

Require yaci.store.analytics.query.enabled=true.

The recommended flow for an agent is analytics-list-tables → analytics-describe-table → analytics-execute-sql. Row limits and timeouts come from the query layer (yaci.store.analytics.query.*); every analytics-execute-sql result reports the applied row_limit and timeout_seconds.

dApp registry

The registry is empty unless you configure local entries or enable the external registry sync (see Configuration).

External metadata

These tools make outbound HTTP calls.

Cardano utilities

No database access and no external calls.

cardano-network-info is worth calling before any slot-range query: it includes the conversion details an agent needs to turn dates into slots correctly.

Configuration

The remaining query-layer settings are listed in Query API & Unified Views.

Security

• analytics-execute-sql is unauthenticated, like the REST /sql endpoint. Statements pass the query layer’s validator and sandbox: a single SELECT/WITH, no file or URL access, read-only engine.
• dapp-registry.external-registry and tools.external-metadata make outbound HTTP calls (GitHub, the Cardano Token Registry, IPFS gateways). Disable them in egress-restricted deployments.
• Tool errors are returned to the agent as a short, sanitized message rather than a stack trace, so the agent can correct its query.