Developers/MCP Server

Receiz MCP Server

@receiz/mcp-server exposes the canonical Receiz SDK rails as agent-callable tools. Agents can verify proof objects, resolve public app-state, bootstrap tenant sessions, publish delegated additions, inspect capabilities, and build production Receiz apps without inventing a parallel integration layer.

npm package OpenAPI Console Create OIDC Client

Authority Boundary

MCP is tooling, not authority.

Receiz proof objects, sealed artifacts, verified local truth, public proof rails, and SDK/API append rails remain the source of truth. MCP exposes those rails to agents and must never replace, rename, or outrank identity, ownership, settlement, public proof, or verification primitives.

Install

Install the MCP server next to the SDK. The server wraps @receiz/sdk; it does not carry a separate data model.

npm install @receiz/mcp-server @receiz/sdk

Run

Public reads can run without a token. Delegated writes require a Receiz Connect/OIDC access token with the scopes for the rail being called. Create the MCP token from Developers Connect using Create Delegated Agent Token.

RECEIZ_BASE_URL=https://receiz.com \
RECEIZ_ACCESS_TOKEN=<delegated-agent-token-from-developers-connect> \
npx -y @receiz/mcp-server

Host Config

Add Receiz to an MCP host so agents can call SDK-backed tools directly.

{
  "mcpServers": {
    "receiz": {
      "command": "npx",
      "args": ["-y", "@receiz/mcp-server"],
      "env": {
        "RECEIZ_BASE_URL": "https://receiz.com",
        "RECEIZ_ACCESS_TOKEN": "<delegated agent token>"
      }
    }
  }
}

Agent Loop

Run receiz_doctor and receiz_capabilities to inspect the app, tenant host, callback URLs, scopes, and available rails.
Use receiz_required_scopes to request the exact OIDC scopes needed for identity, wallet, commerce, app-state, proof, media, domains, customers, and merchants.
Use receiz_mcp_login to open the delegated agent-token path, then use receiz_authorize_url or receiz_ensure_tenant_session when user consent or tenant bootstrap is required.
Use receiz_public_store_resolve or receiz_app_state_resolve for cold-start first paint from public projection truth.
Publish verified additions with receiz_public_store_publish or receiz_app_state_publish using delegated access.
Use receiz_webhook_events_catalog, receiz_webhook_register_endpoint, and receiz_webhook_receiver_scaffold for signed event delivery.
Resolve and inspect proof surfaces with receiz_asset_by_url, receiz_asset_by_id, receiz_inspect_offline_file, receiz_inspect_proof_object, and receiz_proof_query. Artifact verification stays in the SDK shared verifier and requires continuity.

Tool Surface

Diagnostics

receiz_doctorreceiz_capabilitiesreceiz_required_scopesreceiz_runtime_blueprint

Identity and Tenant Sessions

receiz_mcp_loginreceiz_authorize_urlreceiz_ensure_tenant_session

Durable Public App State

receiz_app_state_publishreceiz_app_state_resolvereceiz_app_state_by_urlreceiz_app_state_by_creatorreceiz_app_state_by_namespacereceiz_app_state_by_id

Commerce Store Projections

receiz_public_store_publishreceiz_public_store_resolve

Webhook Delivery

receiz_webhook_events_catalogreceiz_webhook_register_endpointreceiz_webhook_rotate_secretreceiz_webhook_send_test_eventreceiz_webhook_receiver_scaffoldreceiz_webhook_verify_payload

Proof and Public Rails

receiz_inspect_offline_filereceiz_asset_by_urlreceiz_asset_by_idreceiz_inspect_proof_objectreceiz_proof_queryreceiz_wallet_public_ledgerreceiz_action_ledgerreceiz_sports_conformancereceiz_world_public_snapshot

Sports and Settlement Helpers

receiz_pitch_proof_by_witness_idreceiz_card_historyreceiz_transfer_previewreceiz_transfer_requires_confirmationreceiz_pack_open_previewreceiz_marketplace_template_generate

Merchant-Owned Publish

MCP delegated tokens are for agent and server operations. Merchant-owned storefront state should use the merchant Identity Seal or Receiz Key through the SDK signed publish rail. That keeps public-store sync beneath the merchant proof object and avoids treating an agent token as merchant authority.

Use MCP to diagnose, inspect, and resolve. Use publicStore.publishWithIdentityProof when the merchant proof object is the publish authority.

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient({ baseUrl: "https://receiz.com" });

await receiz.publicStore.publishWithIdentityProof({
  keyFile,
  tenantHost: "bjklock.receiz.app",
  merchantReceizId: "bjklock.receiz.id",
  storeStateRecord
});

Resource Templates

Agent hosts can expose stable Receiz URI templates for public proof assets, pitch witnesses, public store projections, SDK docs, and proof object schema guidance.

receiz://asset/{id}receiz://proof/{id}receiz://pitch/{witnessId}receiz://store/{tenantHost}receiz://sdk/docsreceiz://schemas/proof-object-v1