# Loyal Spark

> Base MCP (39 tools) on Base: programs, mint, rewards. lsk_ key; plan limits enforced. /for-agents

- name: io.github.aspekt19/loyal-spark
- version: 1.0.4
- connection class: R1 (autonomous)
- trust: 79/100 flags: no-repository
- quality: 63/100 (needs work)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.aspekt19%2Floyal-spark
- tools: https://api.protogrid.dev/v1/servers/io.github.aspekt19%2Floyal-spark/tools

**An agent can connect on its own if it already holds `X_API_KEY`, `LOYAL_SPARK_TOKEN`.** Remote endpoint behind a static API key or header. The registry never sees the value; the agent fills the placeholder.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "loyal-spark": {
      "type": "http",
      "url": "https://api.loyalspark.online/loyalty-mcp",
      "headers": {
        "x-api-key": "${X_API_KEY}",
        "Authorization": "Bearer ${LOYAL_SPARK_TOKEN}"
      }
    }
  }
}
```

Placeholders to fill: `${X_API_KEY}`, `${LOYAL_SPARK_TOKEN}`.

## Trust

- hygiene: 80
- liveness: 97
- freshness: 100
- provenance: 45
- drivers: +website +reachable +uptime-94% +updated-8d-ago -no-repository
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 63/100 (needs work)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-03-26; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 71 (weight 30)

- pass `tools.descriptions`: every tool has a description
- pass `tools.description_length`: descriptions are concise
- pass `tools.schemas`: every tool has an object input schema
- fail `tools.annotations`: no tool declares readOnlyHint or destructiveHint, so clients cannot tell safe calls from risky ones
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: get_my_profile (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); get_program_workflow_status (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); confirm_mint_fee (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); …
- pass `tools.token_cost`: about 4,917 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 25 (weight 15)

- warn `stability.changes`: 7 tool changes in 30 days
- fail `stability.rug_pull`: 2 tools kept their name but changed most of their description in 30 days; review before trusting them

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 42, about 4,917 tokens to load them all
- tool set hash: f07b390e3f0581748e3ba4e4da373f96
- tools last changed: 2026-10-19T13:01:59.392Z
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.aspekt19/loyal-spark.svg)](https://protogrid.dev/servers/io.github.aspekt19/loyal-spark)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

- 2026-10-19 `mint_loyalty_tokens` changed (description, inputSchema)
  - before: Record mint intent and get a fee-first `calls[]` bundle: protocol fee mint FIRST, then the recipient mint. The protocol fee is charged in the merchant's own loyalty tokens (not USDC). Submit both calls in order (atomically via EIP-5792 send_calls if your wallet supports it), then call confirm_mint_fee (or POST /agent-api/mint/confirm) with the fee tx hash. Unconfirmed fee obligations block future mints.
  - after: Record mint intent and get a fee-first `calls[]` bundle: protocol fee mint FIRST, then the recipient mint. The protocol fee is charged in the merchant's own loyalty tokens (not USDC). Submit both calls in order (atomically via EIP-5792 send_calls if your wallet supports it), then call confirm_mint_fee (or POST /agent-api/mint/confirm) with the fee tx hash. Unconfirmed fee obligations block future mints. Prefer recipient_address (same as REST POST /agent-api/mint); `recipient` is a legacy alias.
- 2026-10-13 `set_store_sales_channel` added
  - Set how this store's customers spend loyalty points: online (checkout code), offline (voucher at the register), or both (the shopper chooses).
- 2026-10-13 `update_store_discount_code` added
  - Mark a Shopify discount code used, or cancel it and return the loyalty points. Same actions as the merchant discount-code journal.
- 2026-10-13 `list_store_discount_codes` added
  - List discount codes for this merchant's Shopify store, plus how customers spend points (online code, register voucher, or both).
- 2026-10-07 `bazaar_pay_and_call` changed (description) **meaning changed**
  - before: Pay and call any x402-paid HTTPS endpoint using the merchant agent's CDP MPC wallet (EIP-3009 exact scheme on Base USDC). Probes the URL for HTTP 402, picks a compatible requirement, signs TransferWithAuthorization via CDP, retries with X-PAYMENT header, and returns the paid response. Requires scope 'mint' and a pre-created CDP wallet. Safety cap: max_usdc (default 0.25, hard limit 10).
  - after: Pay a Loyal Spark x402 URL on api.loyalspark.online with the merchant agent's CDP MPC wallet (EIP-3009 exact scheme, Base USDC). Other hosts are refused before any signature. Requires scope 'mint' and an active CDP wallet. max_usdc default 0.25, hard limit 10.
- 2026-10-01 `create_gift_certificate` changed (description)
  - before: Create a gift / welcome certificate (UDS-style) with a unique 6-character redemption code (LOYAL-XXXXXX). Customer redeems via QR or by entering the code; merchant then mints tokens on-chain. Use for welcome bonuses, promo campaigns, partnership gifts.
  - after: Create a gift / welcome certificate (UDS-style) with a unique random redemption code (LOYAL-XXXX-XXXX-XXXX). Customer redeems via QR or by entering the code; merchant then mints tokens on-chain. Use for welcome bonuses, promo campaigns, partnership gifts.
- 2026-10-01 `check_voucher_status` changed (description) **meaning changed**
  - before: Check voucher status by code or ID. Public endpoint — no API key or authentication required.
  - after: Check voucher status by code or ID. Requires a merchant agent key; only vouchers issued by the key owner's store are returned.

Full history: https://api.protogrid.dev/v1/servers/io.github.aspekt19%2Floyal-spark/changes

## Remotes

- https://api.loyalspark.online/loyalty-mcp (streamable-http, auth api_key ${X_API_KEY}, reachable true, uptime30d 0.9369369)

## Packages

_none_

## Tools (42)

- `activate_loyalty_program`: For legacy ERC-20 programs: returns unpauseUtility + enableMinting calldata. For B20 programs: no-op (already active).
- `bazaar_discover_mcp_servers`: Discover third-party MCP servers published in Coinbase CDP's Bazaar. Read-only. Filter by free-text q and/or network.
- `bazaar_discover_resources`: Discover third-party x402-paid resources published in Coinbase CDP's Bazaar (docs, data feeds, AI inference, etc). Read-only. Filter by free-text q and/or network (e.g. 'base').
- `bazaar_pay_and_call`: Pay a Loyal Spark x402 URL on api.loyalspark.online with the merchant agent's CDP MPC wallet (EIP-3009 exact scheme, Base USDC). Other hosts are refused before any signature. Requires scope 'mint' and an active CDP wallet. max_usdc default 0.25, hard limit 10.
- `bazaar_probe_x402`: GET a candidate x402 URL and, if it responds HTTP 402, return the parsed payment requirements (accepts[]) so the caller can decide whether to pay. HTTPS only. No signing performed.
- `cancel_stale_offers`: Cancel marketplace offers that have been active for more than N days with no completions. Admin-only action tool.
- `check_voucher_status`: Check voucher status by code or ID. Requires a merchant agent key; only vouchers issued by the key owner's store are returned.
- `confirm_mint_fee`: Confirm that the protocol fee transaction for a previous mint/earn was broadcast on Base. Verifies the fee mint on-chain and clears the obligation. Unconfirmed fee obligations block future mints.
- `create_gift_certificate`: Create a gift / welcome certificate (UDS-style) with a unique random redemption code (LOYAL-XXXX-XXXX-XXXX). Customer redeems via QR or by entering the code; merchant then mints tokens on-chain. Use for welcome bonuses, promo campaigns, partnership gifts.
- `create_loyalty_program`: Get factory calldata to deploy a new loyalty token on Base. Defaults to B20 (Base native ERC-20 superset, single tx, active immediately). Pass token_standard='erc20' for the legacy factory. For B20, MINT_ROLE is granted atomically to the merchant admin AND to the agent's CDP wallet (or explicit extra_minters) so autonomous agents can mint with no follow-up transaction.
- `create_personalized_offer`: Create a personalized offer for a specific customer. Use when analytics reveal engagement patterns (e.g., inactive customers, high-value segments).
- `create_reward`: Create a new reward redeemable with loyalty tokens
- `delete_report`: Delete a report that is no longer relevant. Use to clean up outdated or irrelevant reports.
- `earn_points`: Calculate and mint loyalty tokens based on purchase amount and program's cashback rate. Returns a fee-first `calls[]` bundle (protocol fee mint first, then the customer mint) — submit in order, atomically via EIP-5792 if supported, then call confirm_mint_fee (or POST /agent-api/mint/confirm). Unconfirmed fee obligations block future mints.
- `export_customers`: Export customer data for a specific loyalty program. Returns wallet addresses, voucher stats, balances, and tier info. Use for analytics, segmentation, and personalized offers.
- `generate_program_defaults`: Workflow planner: field catalog, required parameters, next_actions, and non-binding examples. External agents must choose their own name, symbol, and economics.
- `get_my_profile`: Get authenticated agent's profile
- `get_platform_info`: Get info about Loyal Spark protocol on Base L2
- `get_platform_stats`: Get global platform statistics across all merchants. Admin-only: requires agent owned by an admin wallet.
- `get_program_analytics`: Get analytics for your loyalty programs
- `get_program_workflow_status`: Explain the next merchant action: current_step, required fields, and ordered next_actions (you provide all parameter values)
- `get_token_balance`: Get loyalty token balance and tier info for a customer
- `list_gift_certificates`: List gift certificates issued by the agent's merchant (with status and redemption info).
- `list_loyalty_programs`: List loyalty programs owned by the agent's merchant
- `list_marketplace_offers`: List active token trading offers on the marketplace
- `list_my_reports`: List your previously submitted reports. Allows reviewing past reports, checking status (new/reviewed/done), and identifying what still needs attention.
- `list_rewards`: List rewards for a loyalty program by token_address. Includes redemption metrics (total vouchers issued, redeemed, and last-30-day counts) for each reward.
- `list_store_discount_codes`: List discount codes for this merchant's Shopify store, plus how customers spend points (online code, register voucher, or both).
- `mark_gift_certificate_minted`: After the merchant submits the on-chain mint transaction for a claimed gift certificate, call this to mark it as minted (status pending_mint → redeemed) and store the mint tx hash.
- `mint_loyalty_tokens`: Record mint intent and get a fee-first `calls[]` bundle: protocol fee mint FIRST, then the recipient mint. The protocol fee is charged in the merchant's own loyalty tokens (not USDC). Submit both calls in order (atomically via EIP-5792 send_calls if your wallet supports it), then call confirm_mint_fee (or POST /agent-api/mint/confirm) with the fee tx hash. Unconfirmed fee obligations block future mints. Prefer recipient_address (same as REST POST /agent-api/mint); `recipient` is a legacy alias.
- `redeem_reward`: Redeem a reward by providing a verified token transfer transaction hash. Creates a voucher for the customer.
- `register_loyalty_program`: Register a deployed token as a loyalty program in the database. B20 tokens are registered as active; legacy ERC-20 as inactive (activate next).
- `revoke_gift_certificate`: Revoke an active gift certificate (status active → revoked). Only the issuing merchant can revoke. Already-redeemed/minted certificates cannot be revoked.
- `send_report`: Send a report to the developer/owner. Use this to submit SEO audits, growth ideas, data reports, anomalies, recommendations, or weekly summaries. The report will appear in the merchant's Agent Reports dashboard.
- `set_store_sales_channel`: Set how this store's customers spend loyalty points: online (checkout code), offline (voucher at the register), or both (the shopper chooses).
- `transfer_loyalty_tokens`: Get calldata to transfer loyalty tokens between wallets
- `update_program_config`: Update default cashback_rate and/or points_per_dollar for a program (same as merchant dashboard sliders)
- `update_program_status`: Update program status in database after onchain activation/pause
- `update_report_status`: Update report status to 'reviewed' or 'done'. Use 'done' when the action items have been completed. Use 'reviewed' to acknowledge a report.
- `update_reward_status`: Activate or deactivate a reward in the catalog. Use to manage reward availability based on analytics.
- `update_store_discount_code`: Mark a Shopify discount code used, or cancel it and return the loyalty points. Same actions as the merchant discount-code journal.
- `use_voucher`: Mark a voucher as used (redeemed by customer at merchant). Merchant-only operation.