MCP tools reference

Axiom Stack Themra is exposed as a Model Context Protocol server over Streamable HTTP at:

https://mcp.axiomstack.dev/mcp

Connect with any MCP client (the official Python/TypeScript SDKs, Claude Desktop, Cursor — see client configuration). Three tools are anonymous-tier (read-only); axiom_request_attestation is authenticated + quota-consuming (see Authentication and Pricing & tiers).

Tool	Tier	Consumes quota
`axiom_quote_fee`	anonymous	no
`axiom_fetch_attestation`	anonymous	no
`axiom_fetch_audit_reference`	anonymous	no
`axiom_request_attestation`	authenticated	yes (1 per call)

axiom_request_attestation

Submit a fresh request and await the Master Broker's signed on-chain attestation. Authenticated-tier; consumes one attestation from your quota. The Themra operator pays the on-chain SOL fee server-side — you are metered by your API key, not charged SOL directly.

Parameter	Type	Default	Notes
`asset_id`	string	—	Equity ticker (e.g. `"TSLA"`). Real-estate address strings are accepted on-chain but class 1 is temporarily unavailable (see below).
`asset_class`	int	—	2 = equity (live). 1 = real estate is temporarily unavailable while repaired. Other classes are out of scope in V1.
`fee_lamports`	int	auto	If omitted, the tool calls `axiom_quote_fee` first.
`data_flags`	int	`255`	u8 bitfield of data layers (default all).
`timeout_seconds`	int	`90`	Total poll timeout for the attestation write.
`poll_interval_seconds`	float	`2.0`	PDA poll cadence.

Returns (shape from a real devnet response):

{
  "asset_class": 2,
  "asset_id": "TSLA",
  "asset_data": { "...": "variant-typed; see hash-only note" },
  "attestations": [
    {
      "provider_pubkey": "9BHC6c5Gv9tUL3DCzRSGkdApdU2QMwh29pxH4Q6zV9xR",
      "valuation_score": 50,
      "confidence_score": 0.85,
      "timestamp": 1779000000,
      "raw_snapshot_hash": "abd67bef…85bc73"
    }
  ],
  "latest_snapshot_hash": "abd67bef…85bc73",
  "manual_audit_required": false,
  "bump": 255,
  "fee_lamports_paid": 8000000,
  "attestation_pda": "8N6kyZcVNRAGbNbc3ygtxTig41zQZyb97ePV8uXa9QKX",
  "write_tx_sig": "5RBri2cGvq5EBQewFTuF89Jni8C2U9tw9iwibeCWkMjpxCjQRzaeD54oStGMzkDmhDnmNvAfoWgtv8jbwQfaLhuQ"
}

attestation_pda + write_tx_sig let you verify the record fully on-chain — see Verify on-chain.
raw_snapshot_hash is the SHA-256 of the raw vendor JSON — the authoritative integrity anchor (see the hash-only model).
Latency: default audit tier ~20 seconds (measured, audit-grade); instant tier (latency_mode="instant", equity) returns data + provisional proof in under 2 s, audit commit async (~30 s).

Errors: 402 quota exhausted (top up at /v1/topup); 401/403 auth; 503 backend; plus tool errors on timeout / provider failure — on which your quota is auto-credited back. Full taxonomy: Error handling.

axiom_quote_fee

Return the listener's current SOL fee floor for a fresh attestation. Anonymous-tier. Call before axiom_request_attestation to learn the live fee (it floats with the SOL price).

Parameter	Type	Default
`asset_class`	int	—
`data_flags`	int	`255`
`margin_pct`	int	`60`

Returns: fee_lamports (int), fiat_cost_usd (float), margin_pct (int), sol_price_usd (float), computed_at (ISO-8601), cached (bool). Example (live): fee_lamports: 8000000, sol_price_usd: 84.04, cached: false.

axiom_fetch_attestation

Read an existing on-chain attestation by its PDA address. Anonymous-tier; read-only; no fee.

Parameter	Type	Notes
`pda_address`	string	base58 Solana PDA.

Returns: the same shape as axiom_request_attestation minus the request-only fields (fee_lamports_paid, attestation_pda, write_tx_sig). Raises OraclePdaNotFound if the PDA has no account or isn't a valid attestation.

axiom_fetch_audit_reference

Capture the listener's current operational-integrity anchor for your audit records. Anonymous-tier; fail-open (never raises).

Parameter	Type	Default
`timeout_seconds`	float	`3.0`

Returns: either oracle_anchor_status: "anchored" with a freshly observed Master-Broker-signed Solana TX + PDA, or oracle_anchor_status: "unanchored" with an oracle_anchor_failure_reason.