@receiz/mcp-server

Production MCP server for agents building and verifying Receiz apps through the canonical @receiz/sdk rails.

v107 operation parity

Version 107.0.0 adds twelve registry-bound tools: identity/profile read, advisory username check, profile plan/execute, proof-media plan/execute, generic bearer-ownership plan/execute, continuity plan/execute, proof-head read, and canonical-receipt verification. Mutation tools inspect current proof state, emit a digest-bound plan, require exact confirmation, execute the matching SDK operation, and report success only after receipt verification.

Local artifact restore/account-state append and signed offline queue execution remain SDK-local because they operate on developer-held bytes and keys. Their global synchronization continues through continuity and canonical admission tools. MCP output is never proof authority.

This package is an agent interface. It is not a new proof authority. Every tool response includes the Receiz authority boundary:

• Source of truth: Receiz SDK, Receiz public proof rails, sealed proof objects, verified local truth, and server append rails.
• MCP authority: false
• MCP role: expose agent-callable tools beneath Receiz proof/object truth.

v107 Application Contract Compiler

The MCP server exposes the shared @receiz/sdk application compiler through receiz_project_inspect, receiz_app_contract_create, receiz_app_plan, receiz_app_apply, receiz_app_check, receiz_app_upgrade, and receiz_app_explain.

Inspection, contract proposals, planning, checking, upgrade planning, and explanation are read-only. receiz_app_apply first returns every affected file and a deterministic digest. It writes only after the caller supplies that exact digest as explicit confirmation. All paths remain inside the explicitly supplied repository root, and repeating an applied plan produces no changes.

Every result states that MCP is not proof authority. Repository inspection does not verify an artifact. Verification remains the SDK's continuity-bound verification.verifyArtifact, and proof-object creation remains authenticated native Record before Seal.

Schema resources are available at receiz://schemas/app-contract-v1, receiz://schemas/integration-plan-v1, receiz://schemas/upgrade-rules-v1, and receiz://schemas/generated-files-v1.

Install

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

The matching @receiz/ai-skills package is installed with both packages. Agent hosts can load all thirty-one authoritative skill directories from node_modules/@receiz/ai-skills; MCP resources and the skills teach the same continuity-bound verification law.

Run the server:

npx -y @receiz/mcp-server

For local development in this repo:

pnpm mcp:test
pnpm mcp:build

Environment

Public reads work without a bearer token when the underlying Receiz rail is public.

Delegated writes require a Receiz-issued Connect/OIDC access token. Create one from /developers/connect with Create Delegated Agent Token. The dashboard shows the bearer token once, returns a revocation token ID, and labels actions with an agent:* audit label.

RECEIZ_BASE_URL=https://receiz.com
RECEIZ_ACCESS_TOKEN=<delegated-agent-access-token>
receiz-mcp

Use RECEIZ_CONNECT_ACCESS_TOKEN as an alias if that is how your app stores delegated Connect access. Run receiz_mcp_login from an MCP host to get the dashboard URL, recommended scopes, exact config snippet, and an OIDC authorize URL when you pass clientId, redirectUri, and codeChallenge.

MCP Host Config

Claude Desktop / Cursor-style config:

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

Tools

Core diagnostics:

• receiz_doctor
• receiz_capabilities
• receiz_required_scopes
• receiz_runtime_blueprint

Identity and tenant sessions:

• receiz_authorize_url
• receiz_mcp_login
• receiz_ensure_tenant_session

Durable public app state:

• receiz_app_state_publish
• receiz_app_state_resolve
• receiz_app_state_by_url
• receiz_app_state_by_creator
• receiz_app_state_by_namespace
• receiz_app_state_by_id

Commerce/store projections:

• receiz_public_store_publish
• receiz_public_store_resolve

receiz_public_store_publish is the delegated agent/server write lane. For merchant-owned storefront state, use the SDK signed publish lane:

await receiz.publicStore.publishWithIdentityProof({
  keyFile,
  tenantHost,
  merchantReceizId,
  storeStateRecord,
});

That path uses the merchant Identity Seal / Receiz Key as authority and does not require RECEIZ_ACCESS_TOKEN.

Proof resolution and inspection (not verification):

• receiz_inspect_offline_file (shape inspection only; always verified: false)
• receiz_asset_by_url
• receiz_asset_by_id
• receiz_inspect_proof_object
• receiz_proof_query

Receiz public rails:

• receiz_wallet_public_ledger
• receiz_action_ledger
• receiz_sports_conformance
• receiz_world_public_snapshot
• receiz_pitch_proof_by_witness_id
• receiz_card_history

Previews and templates:

• receiz_transfer_preview
• receiz_transfer_requires_confirmation
• receiz_pack_open_preview
• receiz_marketplace_template_generate

Webhooks:

• receiz_webhook_events_catalog
• receiz_webhook_register_endpoint
• receiz_webhook_rotate_secret
• receiz_webhook_send_test_event
• receiz_webhook_receiver_scaffold
• receiz_webhook_verify_payload

Use receiz_webhook_events_catalog first, then receiz_webhook_register_endpoint with the payment preset or explicit event types. Register and rotate return the plaintext endpoint secret once. receiz_webhook_receiver_scaffold returns a receiver that verifies delivery before parsing and reminds the agent to verify the underlying proof object, ownership append, or settlement ledger event before admitting product truth.

Sandbox:

• receiz_sandbox_seed_store
• receiz_sandbox_checkout

Semantic v107 operations:

• receiz_app_repair previews repository-confined repairs and requires the exact digest before writing.
• receiz_proof_trace invokes canonical artifact verification for byte-bearing inputs; inspection-only input receives no verified verdict.
• receiz_webhook_replay verifies the captured delivery, previews its digest, and requires exact confirmation for idempotent replay admission.
• receiz_scope_explain reads the canonical SDK capability descriptor.
• receiz_release_qualify returns read-only repository and receiz.sdk.conformance_report.v1 evidence.

Resource Templates

Agent hosts can expose these Receiz resource templates:

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

Full Receiz App Loop

An agent can build a full Receiz app with this sequence:

1. Run receiz_doctor and receiz_capabilities.
2. Use receiz_required_scopes for the app rails it needs.
3. Use receiz_mcp_login, receiz_authorize_url, or receiz_ensure_tenant_session for Connect/OIDC setup.
4. Use receiz_public_store_resolve or receiz_app_state_resolve for cold-start first paint.
5. Render known verified projection truth immediately.
6. Publish verified additions with receiz_public_store_publish or receiz_app_state_publish.
7. Use receiz_asset_by_url, receiz_asset_by_id, and receiz_inspect_proof_object to resolve and inspect proof surfaces. Use @receiz/sdk verification.verifyArtifact(file) for the indivisible integrity-and-continuity verdict.
8. Use receiz_webhook_events_catalog, receiz_webhook_register_endpoint, and receiz_webhook_receiver_scaffold for event delivery.
9. Use ledger/world/sports/proof-query tools for dashboards and advanced experiences.

Authority Boundary

Receiz truth hierarchy is preserved:

1. Sealed artifact truth
2. Deterministic proof object state
3. Verified local truth
4. Verified register append
5. Authenticated SDK/API projection
6. MCP tool result

MCP may inspect, resolve, publish through delegated SDK calls, and report. MCP must never replace, rename, or outrank a Receiz proof object, identity primitive, settlement primitive, ownership surface, or public proof surface.