HMS x402 Data Origins MCP server
Commit Nov 12, 2026Exposes real estate data refinery and car-rental rate tools to AI agents using a tokenless x402 payment system on Base.
Also known as areshms/hms-mcp, hms-mcp
- Stars
- 0
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 12, 2026
- License
- —
What is HMS x402 Data Origins MCP?
HMS x402 Data Origins exposes real estate data refinery and car-rental rate tools to AI agents using a tokenless x402 payment system on Base. It exposes 18 tools, such as refinery_search, refinery_properties, refinery_properties_zpid.
Summary generated from the project's README
About HMS x402 Data Origins MCP server
Accessing real estate intelligence and rental market rates through AI agents is possible with this remote MCP server. It connects agents to two distinct data sources: the RE Data Refinery and HMS Storefront Data. Developers use it via a streamable HTTP transport using JSON-RPC 2.0, which eliminates the need for traditional API keys or wallet management.
While several tools like refinery_health and sf_v1_coverage are free, others require payment. The server utilizes a tokenless x402 v2 system on the Base network. When an agent calls a paid tool such as refinery_search or sf_v1_rental_rates, the server returns a payment challenge. An x402-capable agent then settles the USDC amount on Base and re-calls the tool with the payment header to receive the requested data. This setup allows for granular, per-call pricing ranging from $0.02 for tax history to $2.50 for cash buyer information.
What you can do with it
- 1Analyze property price trendsAsk an AI agent to retrieve the historical price data for a specific property using its ZPID.
- 2Research local rental marketsRequest live rental rate information for a specific city to evaluate investment potential.
- 3Identify real estate opportunitiesHave an agent search for active foreclosures or upcoming tax sales in a given area.
- 4Find local cash buyersInstruct an AI to locate lists of cash buyers for real estate transactions.
Written from the project's README. Every use case is checked against a quote from it.
How to install HMS x402 Data Origins MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HMS x402 Data Origins MCP in Claude Code
$ claude mcp add --transport http hms-mcp https://hms-mcp.ares-hms.workers.dev/mcpInstall HMS x402 Data Origins MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hms-mcp": {
"url": "https://hms-mcp.ares-hms.workers.dev/mcp"
}
}
}Install HMS x402 Data Origins MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hms-mcp": {
"type": "http",
"url": "https://hms-mcp.ares-hms.workers.dev/mcp"
}
}
}Install HMS x402 Data Origins MCP in VS Code CLI
$ code --add-mcp '{"name":"hms-mcp","type":"http","url":"https://hms-mcp.ares-hms.workers.dev/mcp"}'Install HMS x402 Data Origins MCP in Codex
$ codex mcp add hms-mcp --url https://hms-mcp.ares-hms.workers.dev/mcpInstall HMS x402 Data Origins MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hms-mcp] url = "https://hms-mcp.ares-hms.workers.dev/mcp"
Install HMS x402 Data Origins MCP in Gemini CLI
$ gemini mcp add -s user --transport http hms-mcp https://hms-mcp.ares-hms.workers.dev/mcpInstall HMS x402 Data Origins MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hms-mcp": {
"url": "https://hms-mcp.ares-hms.workers.dev/mcp",
"type": "http"
}
}
}HMS x402 Data Origins MCP tools 18
Detected from the READMErefinery_searchrefinery_propertiesrefinery_properties_zpidrefinery_properties_zpid_price_historyrefinery_properties_zpid_tax_historyrefinery_properties_zpid_schoolsrefinery_foreclosuresrefinery_tax_salesrefinery_auctionsrefinery_preforeclosuresrefinery_cash_buyersrefinery_health
Show all 18 toolsShow fewer tools
refinery_creditssf_v1_rental_ratessf_v1_truck_sleep_stopssf_healthsf_v1_coveragehms_get_origins
Automated checks
Ran Nov 14, 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 reachableareshms/hms-mcp is public and reachablegithub.com/areshms/hms-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-12github.com/areshms/hms-mcp ↗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 model18 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 72 msPass
README
View on GitHubhms-mcp — HMS x402 Data Origins MCP Server
Remote MCP server (Streamable HTTP) that exposes both HMS x402 data origins as MCP tools for AI agents. Tokenless: no API keys, no wallets. Free tools answer directly; paid tools surface the origin's x402 v2 Payment Required challenge (USDC on Base) so an x402-capable agent can settle and re-call.
- Endpoint:
https://hms-mcp.ares-hms.workers.dev/mcp - Transport: Streamable HTTP (POST, JSON-RPC 2.0). No SSE required.
- Owner: HMS LLC (Blake Hightower) —
areshms
Origins behind this server
| Origin | Base URL | openapi.json |
|---|---|---|
| RE Data Refinery | https://re-data-refinery.ares-hms.workers.dev | /openapi.json |
| HMS Storefront Data | https://storefront-data-hms.ares-hms.workers.dev | /openapi.json |
Connect (ready-to-copy configs)
{ "mcpServers": { "hms-mcp": { "url": "https://hms-mcp.ares-hms.workers.dev/mcp" } } }
Tools (19 + meta)
| Tool | Maps to | Price (per call) |
|---|---|---|
refinery_search |
GET /search | $0.05 |
refinery_properties |
GET /properties (city filter) | $0.03 |
refinery_properties_zpid |
GET /properties/{zpid} | $0.03 |
refinery_properties_zpid_price_history |
GET /properties/{zpid}/price-history | $0.02 |
refinery_properties_zpid_tax_history |
GET /properties/{zpid}/tax-history | $0.02 |
refinery_properties_zpid_schools |
GET /properties/{zpid}/schools | $0.02 |
refinery_foreclosures |
GET /foreclosures | $0.05 |
refinery_tax_sales |
GET /tax-sales | $0.05 |
refinery_auctions |
GET /auctions | $0.05 |
refinery_preforeclosures |
GET /preforeclosures?county= (19 Ohio counties) | $0.05 |
refinery_cash_buyers |
GET /cash-buyers | $0.50–$2.50 |
refinery_health |
GET /health | Free |
refinery_coverage / refinery_v1_coverage |
GET /coverage (real record counts) | Free |
refinery_credits |
GET /credits | Free |
sf_v1_rental_rates |
GET /v1/rental/rates?city= | $0.03 (live) |
sf_v1_truck_sleep_stops |
GET /v1/truck/sleep-stops | Free (until data) |
sf_health |
GET /health | Free |
sf_v1_coverage |
GET /v1/coverage (honesty gate) | Free |
hms_get_origins |
meta: origins + payment flow | Free |
How paid tools work (tokenless)
- Call a paid tool. The wrapper forwards to the origin and returns its HTTP 402 payload, including the x402 v2 challenge (
network: eip155:8453(Base),token: USDC,amount,receiver,facilitator). - Settle the challenge with any x402 client (USDC on Base).
- Re-call the same tool with the same params, passing the produced header value as
x402_payment— the wrapper forwards it asX-PAYMENTand returns your data.
The wrapper never holds funds or keys. Prices are set by the origin workers.
Deployment
Cloudflare Worker (plain JS, no build step): npx wrangler deploy in this directory. Uses Cloudflare service bindings to call the two origin workers on the same account (re-data-refinery, storefront-data-hms) — same-account *.workers.dev fetches are blocked (error 1042) without bindings.
Local verification:
curl -s -X POST https://hms-mcp.ares-hms.workers.dev/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
Known limitation
Cloudflare's workers.dev edge bans the bare Python-urllib/x client signature (error 1010, browser_signature_banned) across all *.workers.dev hosts — this is zone-level, not something this worker can allowlist. Python clients that send any normal User-Agent (e.g. requests with a browser-like UA) are unaffected.
License
MIT
HMS x402 Data Origins MCP questions
How do I add HMS x402 Data Origins MCP to Claude Code?
Run claude mcp add --transport http hms-mcp https://hms-mcp.ares-hms.workers.dev/mcp in your terminal. Add --scope user to make it available in every project.
How do I add HMS x402 Data Origins MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does HMS x402 Data Origins MCP provide?
It exposes 18 tools, including refinery_search, refinery_properties, refinery_properties_zpid, refinery_properties_zpid_price_history, refinery_properties_zpid_tax_history.
How do I pay for tools that are not free?
Paid tools return an x402 v2 Payment Required challenge (USDC on Base) which you can settle with an x402-capable agent before re-calling the tool.
What happens if I use a Python-urllib client?
Cloudflare's edge bans the bare Python-urllib client signature, so you should use a client that sends a normal User-Agent.