English Français العربية

Merchant Context

Official registry AI and agents

Resolve sourced merchant facts and safe actions before an agent acts.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http merchant-context 'https://api.merchant.atomandbits.com/mcp'
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "merchant-context": {
            "type": "http",
            "url": "https://api.merchant.atomandbits.com/mcp"
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Merchant Context
  2. Canonical sources
  3. Status
  4. Agent endpoints
  5. Quick start
  6. Add it to an agent
  7. Design rules
  8. Agent service
  9. Contributing
  10. License

Merchant Context

Merchant Context is an open merchant preflight for agent builders.

It starts with a practical question:

Can an agent tell what you sell, who it is for, what it costs, which rules apply, and what action comes next without guessing?

This repo contains:

Canonical sources

The domain schema and schema/merchant-context.schema.json must stay semantically equal. Versioned releases preserve old contracts.

Status

This is an early public draft from Atom & Bits. It is not a new payment or checkout protocol. It does not certify ACP, UCP, MCP, A2A, x402, or Web Bot Auth support.

The UCP profile declares no services, checkout capabilities, or payment handlers. It gives agents an explicit discovery response without claiming operations that do not exist.

The goal is to give merchants one testable context layer that can map to those systems as they mature.

No outside adoption is claimed from internal tests, registry views, repository activity, or self-funded payments.

Agent endpoints

  • MCP: https://api.merchant.atomandbits.com/mcp
  • Free MCP tool: resolve_merchant
  • Free HTTP: POST https://api.merchant.atomandbits.com/v1/resolve
  • Paid MCP tool: refresh_merchant
  • Paid HTTP x402: POST https://api.merchant.atomandbits.com/v1/refresh
  • Price: $0.01 USDC on Base
  • First verified settlement: Base transaction 0x2f0f…57af

The first paid call settled on 2026-08-04 and returned a live inspection of https://merchant.atomandbits.com.

Quick start

  1. Work through CHECKLIST.md.
  2. Copy examples/saas.json.
  3. Replace every sample value with a fact from your own site or system.
  4. Keep prices, stock, policies, and action URLs current.
  5. Run python3 scripts/validate.py before publishing.

Add it to an agent

The remote MCP endpoint works with clients that support Streamable HTTP:

https://api.merchant.atomandbits.com/mcp

Start with resolve_merchant.

It is free.

A cache hit makes no merchant fetch and no paid inspection call.

See the agent integration guide for Codex, Claude Code, Gemini CLI, Cursor, and the OpenAI Responses API.

Agents that support the open Agent Skills format can use skills/merchant-context.

Design rules

  • Facts beat slogans.
  • A URL is not an API.
  • Agents must not infer price, stock, policy, or authority.
  • Each claim should name its source and update time.
  • A purchase or other high-impact action should state when human approval is required.
  • Existing standards win. Map to them instead of inventing a private dialect.

Agent service

The worker directory contains the hosted MCP service under test. It exposes:

  • resolve_merchant, a free sourced merchant record with freshness, unknowns, safe actions, and attribution;
  • search_merchants, a neutral search over cached sourced records;
  • compare_offers, a sourced comparison that keeps unknown values;
  • get_safe_actions, a merchant-owned action handoff with approval and recovery rules;
  • preflight, the reusable resolution and action gate;
  • check_merchant, a free merchant-site diagnostic;
  • refresh_merchant, a $0.01 x402 fresh inspection that needs explicit approval;
  • inspect_merchant, a first-release compatibility alias for paid refresh;
  • direct HTTP routes under /v1; and
  • /.well-known/merchant-context, a public service record for agents and registries.

The inspector accepts public HTTPS origins only. It blocks local and IP targets, checks each redirect, caps response size and time, and returns no page body. The payment path records hashes, not wallet addresses or signed payment tokens.

Run its local checks:

cd worker
npm install
npm test
npm run typecheck
npx wrangler deploy --dry-run

Contributing

Issues, examples, and corrections are welcome. Read CONTRIBUTING.md before opening a pull request.

License

MIT. See LICENSE.

Frequently asked questions

What is Merchant Context?

Resolve sourced merchant facts and safe actions before an agent acts.

How do I install Merchant Context?

It runs as a remote server. In Claude Code: claude mcp add --transport http merchant-context 'https://api.merchant.atomandbits.com/mcp'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Merchant Context need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Merchant Context open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Merchant Context?

It is published by ihint. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.