Merchant Context MCP server
Commit Oct 30, 2026Provides agents with verified merchant facts, product details, and safe action handoffs to prevent guessing during commerce interactions.
Also known as ihint/merchant-context, merchant-context
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.0
- Last commit
- Oct 30, 2026
- License
- MIT
What is Merchant Context MCP?
Merchant Context provides agents with verified merchant facts, product details, and safe action handoffs to prevent guessing during commerce interactions.
Summary generated from the project's README
About Merchant Context MCP server
Providing agents with verified merchant facts and product details is the primary function of Merchant Context. This service helps agent builders prevent guesswork during commerce interactions by offering a testable context layer for prices, stock, and policies. It is designed to ensure that AI agents do not infer critical information but instead rely on sourced records that include freshness and attribution.
Developers can connect to the remote MCP endpoint using clients that support Streamable HTTP. The service provides a free tool called resolve_merchant for sourcing merchant records, along with search_merchants and compare_offers. For real-time updates, the paid refresh_merchant tool allows for a fresh inspection at a cost of $0.01 USDC on Base. The system also includes get_safe_actions to manage merchant-owned action handoffs with specific approval and recovery rules.
Written from the project's README. Every use case is checked against a quote from it.
How to install Merchant Context MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Merchant Context MCP in Claude Code
$ claude mcp add --transport http merchant-context https://api.merchant.atomandbits.com/mcpInstall Merchant Context MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"merchant-context": {
"url": "https://api.merchant.atomandbits.com/mcp"
}
}
}Install Merchant Context MCP in VS Code
.vscode/mcp.json
{
"servers": {
"merchant-context": {
"type": "http",
"url": "https://api.merchant.atomandbits.com/mcp"
}
}
}Install Merchant Context MCP in VS Code CLI
$ code --add-mcp '{"name":"merchant-context","type":"http","url":"https://api.merchant.atomandbits.com/mcp"}'Install Merchant Context MCP in Codex
$ codex mcp add merchant-context --url https://api.merchant.atomandbits.com/mcpInstall Merchant Context MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.merchant-context] url = "https://api.merchant.atomandbits.com/mcp"
Install Merchant Context MCP in Gemini CLI
$ gemini mcp add -s user --transport http merchant-context https://api.merchant.atomandbits.com/mcpInstall Merchant Context MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"merchant-context": {
"url": "https://api.merchant.atomandbits.com/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableihint/merchant-context is public and reachablegithub.com/ihint/merchant-context ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/ihint/merchant-context ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 1399 msPass
README
View on GitHubMerchant 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:
- a merchant publishing checklist;
- a draft merchant-context schema;
- a worked SaaS example; and
- a map of the main commerce and discovery standards.
Canonical sources
- Product and machine brief: https://merchant.atomandbits.com/llms.txt
- Version 0.1 schema: https://merchant.atomandbits.com/schema/merchant-context-v0.1.json
- UCP discovery: https://merchant.atomandbits.com/.well-known/ucp
- Open source and history: https://github.com/ihint/merchant-context
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
- Work through CHECKLIST.md.
- Copy examples/saas.json.
- Replace every sample value with a fact from your own site or system.
- Keep prices, stock, policies, and action URLs current.
- Run
python3 scripts/validate.pybefore 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.
Merchant Context MCP questions
How do I add Merchant Context MCP to Claude Code?
Run claude mcp add --transport http merchant-context https://api.merchant.atomandbits.com/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Merchant Context MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.