cypher-mcp

cypher-mcp

Monetized graph answers over Bitcoin Lightning. A Tollbooth-DPYC Operatorthat sells priced answers from a graph — operator-authored, parameterized,named Cypher query templates — not raw database access.

The OSS Neo4j MCP servers are a free pipe to a database the operatorseparately expenses (Neo4j invoice) and separately bills for (Stripe stack).cypher-mcp collapses infrastructure cost, application billing, and accesscontrol into one metered MCP surface: the operator stops selling seats andstarts selling answers, settled in sats, with no Stripe stack and no Neo4jinvoice passed to the customer.

Live at https://cypher-mcp.fastmcp.app/mcp.

How it works

Two planes, cleanly separated:

• Settlement / identity plane — Neon + Nostr + Tollbooth, shared withevery other DPYC operator. It never knows a graph exists.
• Value-delivery plane — Bolt → Neo4j, sealed inside the tool handlers(graph.py), opened and torn down per request (no pool). The backing storeis an implementation detail invisible to patrons, so it can be swappedwithout changing the MCP surface.

Three conceptual layers:

Status: live, with named tools. L1 + L2 are shipped and serving real,billed answers — an operator adopted by an Authority, AuraDB-backed, withrefund-on-raise verified end to end. Named tools are now live (L3 toolsynthesis): an operator can publish_tool(key) to project a query as afirst-class, typed tool (e.g. cypher_find_airline_flights(from_city, to_city)), priced individually in Pricing Studio. Per-key parametric pricingformulas remain a later step — see CHANGELOG.md.

Tools

Patron (priced):

• cypher_execute_query_by_key(key, params) — run a published query. Yousupply only parameters; the operator owns the query text, and parametersbind as Cypher $params (never string-interpolated). You're charged onlyfor a delivered answer — an unknown key, invalid parameters, or a failedquery rolls back the debit (refund-on-raise).

Plus the standard DPYC surface from the wheel: cypher_check_balance,cypher_check_price, cypher_purchase_credits, Secure Courier, npub proof,Oracle delegation, account statements, constraint-based dynamic pricing, etc.

Operator-only (restricted, unpriced) — the authoring plane:

• cypher_create_query / cypher_update_query / cypher_get_query /cypher_list_queries / cypher_delete_query
• cypher_publish_tool(key) / cypher_unpublish_tool(key) — project a query asa first-class, typed named tool (or retire it). See Named tools below.

Raw Cypher never reaches patrons — only named, parameterized templates.

Authoring in Neo4j's own UI — no second editor to learn

A DB-analyst refines templates in Neo4j Browser, not in a bespoke tool.cypher_get_query(key) returns the template plus an edit_url — a deeplink into the hosted Neo4j Browser (browser.neo4j.io) that pre-targets theoperator's AuraDB and loads the statement in edit mode (cmd=edit).Refine it with autocomplete, run-to-test, visualization, and PROFILE; thensave it back with cypher_update_query. The template is just a string flowingover MCP — no files, no desktop, no exported bundles. The link carries theDBMS URI but never the password, and get_query is operator-only, so neitherever reaches a patron.

Named tools — publish a query as its own tool

cypher_publish_tool(key) projects a catalog query as a first-class MCP toolnamed cypher_<key> whose flat, typed parameters come from the query's schema —e.g. cypher_find_airline_flights(from_city, to_city). An agent then calls it byname with typed params instead of execute_query_by_key(key, params). Internallyevery named tool funnels through the same shared executor (look the storedCypher up by key → parameter-bind → run), so there is one code path and the samerefund-on-raise guarantee. A published tool registers unpriced — it appears inPricing Studio like any new tool; set its price there (calls return "not priced yet(TBD)" until you do). cypher_unpublish_tool(key) retires the tool (the queryitself stays, still runnable by key). Published tools survive restarts(re-materialized from the catalog); reconnect to observe tool-list changes.

The synthesis machinery is a generic tollbooth-dpyc primitive(register_dynamic_tool) — named Cypher queries are one realization; the sameprimitive can back a synthesized tool with a REST call, SQL, or a stored prompt.

Onboarding (operator)

1. Request adoption from an Authority (the deferred courtship —request_adoption) or be registered directly. Either way the Authorityprovisions an isolated Neon tenant automatically.
2. Deliver operator secrets via Secure Courier(cypher_request_credential_channel, service cypher-operator):
   • neo4j_uri, neo4j_user, neo4j_password — the graph store(e.g. a Neo4j AuraDB instance)
   • btcpay_host, btcpay_api_key, btcpay_store_id — Lightning
3. Author your catalog with cypher_create_query; patrons then execute by key.

Develop

pip install -e ".[dev]"
pytest -v
python -m cypher_mcp.server   # needs TOLLBOOTH_NOSTR_OPERATOR_NSEC

Deployed on Prefect Horizon (FastMCP runtime); see .fastmcp.yaml. The onlyenv var required to boot is TOLLBOOTH_NOSTR_OPERATOR_NSEC — every othersecret arrives via Secure Courier.

DPYC Ecosystem

Prior Art & Attribution

The methods, algorithms, and implementations contained in this repository mayrepresent original work by Lonnie VanZandt, first published on June 15, 2026.This public disclosure establishes prior art under U.S. patent law(35 U.S.C. 102).

All use, reproduction, or derivative work must comply with the Apache License2.0 included in this repository and must provide proper attribution to theoriginal author per the NOTICE file.

How to Attribute

If you use or build upon this work, please include the following in yourdocumentation or source:

Based on original work by Lonnie VanZandt and Claude.ai
Originally published: June 15, 2026
Source: https://github.com/lonniev/cypher-mcp
Licensed under Apache License 2.0

Visit the technologist's virtual cafe for Bitcoin advocates and coffeeaficionados at stablecoin.myshopify.com.

Patent Notice

The author reserves all rights to seek patent protection for the novel methodsand systems described herein. Public disclosure of this work establishes apriority date of June 15, 2026. Under the America Invents Act, the authorretains a one-year grace period from the date of first public disclosure tofile patent applications.

Note to potential filers: This public repository and its full Git historyserve as evidence of prior art. Any patent application covering substantiallysimilar methods filed after the publication date of this repository may besubject to invalidation under 35 U.S.C. 102(a).

Further Reading

The Phantom Tollbooth on the Lightning Turnpike— the full story of how we're monetizing the monetization of AI APIs, andthen fading to the background.

Trademarks

DPYC™, Tollbooth DPYC™, and Don't Pester Your Customer™ aretrademarks of Lonnie VanZandt. SeeTRADEMARKS.mdin the dpyc-community repository for usage guidelines.

License

Apache License 2.0 — see LICENSE and NOTICE for details.

Because in the end, the tollbooth was never the destination. It was alwaysjust the beginning of the journey.