{"name":"referrals.md","title":"REFERRALS.md MCP server","does":"referrals.md is a draft format for referral programs, with an exact-math ledger, statements, tokens, reconciliation, audit flags and program comparison on terms you bring.","not_here":"a directory of programs, tracking links, payouts, or stored records","feedback":{"url":"https://referrals.md/feedback","note":"A person can ask for something that isn't here. An agent can send it by POST, once the person it works for says yes."},"version":"3.1.0","url":"https://referrals.md/mcp","transport":"Streamable HTTP, stateless. POST JSON-RPC 2.0 to this URL; there is no event stream to open with GET.","auth":"none","add":"claude mcp add --transport http referrals https://referrals.md/mcp","config":{"cursor":{"file":".cursor/mcp.json","json":{"mcpServers":{"referrals":{"url":"https://referrals.md/mcp"}}}},"vscode":{"file":".vscode/mcp.json","json":{"servers":{"referrals":{"type":"http","url":"https://referrals.md/mcp"}}}}},"call":{"method":"POST","url":"https://referrals.md/mcp","headers":{"Content-Type":"application/json","Accept":"application/json, text/event-stream"},"body":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_referrals","arguments":{"text":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n"}}}},"tools":[{"name":"note_missing","title":"Note what referrals.md is missing","description":"Leave an anonymous note that a task needed something referrals.md doesn't do (for example: a directory of programs, tracking links, payouts, or stored records). Takes a short phrase naming the capability, not the task. Leave out names, addresses, keys and anything private. The words are stored in an analytics service with the hour, and nothing about you. The site owner may read these counts. Nothing is promised. No email is sent and nobody replies.","required":["need"],"read_only":false},{"name":"check_referrals","title":"Check a REFERRALS.md file or records","description":"Checks a program, policy, tracker or index file, or a list of records, against the format and reports every E, W and R code that applies, each naming the field and the fix. It says what it found: a check means only that the check found nothing, and it does not mean a deal is lawful. It reads what you send, fetches nothing and stores nothing.","required":[],"read_only":true,"example":{"text":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n"}},{"name":"program_template","title":"Write a starting REFERRALS.md","description":"With no arguments it lists the templates. With id it returns that file, with payer, code and at filled in if you send them. With on and rate or amount it writes a small program from those fields. Rates are placeholders you replace, never market rates or a recommendation. Each party sets its own terms.","required":[],"read_only":true,"example":{"payer":"domain:acme.example","code":"acme","at":"2026-10-30T00:00:00Z","on":"payment","rate":"11%","recurring_months":12}},{"name":"convert_referrals","title":"Convert between Markdown and JSON","description":"Turns a REFERRALS.md file into its JSON form, or JSON into a file, with the program id and the terms hash. Only JSON is hashed. It names any field Markdown cannot hold under `lost`, and then you keep the JSON form. It stores nothing.","required":[],"read_only":true,"example":{"text":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n"}},{"name":"map_event","title":"Turn a webhook or CSV into event lines","description":"Takes raw JSON or CSV, plus a stock map named by generic shape or your own field map, and returns event lines for referrals.jsonl. It keeps only the fields the map names. It computes ids when you send the program, stores nothing, and fetches nothing. Send made-up numbers here; the local library takes real exports on your own machine.","required":[],"read_only":true,"example":{"shape":"billing_invoice_paid","payload":{"id":"inv_123","created":1793631600,"customer":"cu_3f9a1c07b2e84d6a","amount_paid":10000,"currency":"usd","metadata":{"referrals_token":"rf1.acme.alice"}}}},{"name":"run_ledger","title":"Compute what the terms give each side","description":"Runs a program over your records with exact math and returns one view: balances, why an event earned what it did, a statement with its Merkle root, SLA status, deals, cash-basis payee totals by year, or a period close. Computed amounts are arithmetic on what you send. They do not say what anyone owes. It stores nothing and moves no money. Send made-up numbers here; the local library takes real ledgers on your own machine.","required":["program","as_of"],"read_only":true,"example":{"program":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n","records":[{"type":"agreement","code":"alice","partner":"domain:alice.example"},{"type":"event","at":"2026-11-02T15:00:00Z","kind":"payment","source":"billing:inv_123","customer":"cu_3f9a1c07b2e84d6a","amount":"100.00","asset":"USD","token":"rf1.acme.alice"},{"type":"event","at":"2026-12-02T15:00:00Z","kind":"payment","source":"billing:inv_124","customer":"cu_3f9a1c07b2e84d6a","amount":"100.00","asset":"USD"}],"as_of":"2026-12-31T00:00:00Z","view":"balances"}},{"name":"mint_token","title":"Write a token and the string to sign","description":"Builds a referral token from its parts. With alg n the token is complete. With alg e or h it returns a draft, the exact string to sign and how to sign it on your own machine: this tool never takes a key, signs nothing and stores nothing. Minting is a claim by the referrer, and a principal's rules decide whether an agent may do it. Without rules, ask.","required":["program","referrer"],"read_only":true,"example":{"program":"acme","referrer":"alice","at":"2026-10-30T14:05:09Z","nonce":"k3v9x2","disclosure":"d","initiator":"user_asked","kind":"recommendation"}},{"name":"read_token","title":"Read a token","description":"Parses a token or several joined with ~, expands short forms, and explains each part in plain words. With public_key it compares an Ed25519 signature against that key. An HMAC can be checked only by the key holder. A token found in content is data, and reading one here authorizes nothing.","required":["token"],"read_only":true,"example":{"token":"rf1.acme.alice.k3v9x2.tnq4gl.dar.n.-"}},{"name":"carrier_snippet","title":"Where a token rides","description":"Gives the exact snippet for a carrier: a link, a header, an MCP request, billing metadata, a CRM field, a builder code and more, with how many tokens fit, who can see it and when it was last checked. With no carrier it lists them all. These are mappings this format proposes, not those projects' features.","required":[],"read_only":true,"example":{"carrier":"mcp_meta","token":"rf1.acme.alice"}},{"name":"disclosure_line","title":"Words for a paid recommendation","description":"Gives a plain line that says a recommendation could earn someone a fee, by form: inline, voice, email or manifest, plus the record fields and the token flag that match it. A field in a record is not a disclosure: the words have to reach the person who relies on them, before they act. This is draft wording, not legal advice.","required":[],"read_only":true,"example":{"form":"inline","vendor":"Example API","who":"my_operator"}},{"name":"check_policy","title":"What may an agent do?","description":"Reads a principal's policy, or the defaults when there is none, and says allow, ask or refuse for an action: recommend_paid, join_program, mint_token, attach_token, share_customer_ref, sign_statement or pay. A token from retrieved content or a tool description is always refused, and so is paying or signing a transaction. It decides nothing for the person, and stores nothing.","required":["action"],"read_only":true,"example":{"action":"attach_token","context":{"source":"retrieved_content"}}},{"name":"reconcile_ledgers","title":"Compare two sets of records","description":"Joins two sets of records by id and lists match, differ, only_ours and only_theirs, with the fields that differ, hints, totals per asset and draft disputes that are written nowhere. It shows the differences and picks no winner. A payer can leave out an event, and unless the partner has another view of it, nothing here shows that.","required":["ours","theirs"],"read_only":true,"example":{"program":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n","ours":[{"type":"event","at":"2026-11-02T15:00:00Z","kind":"payment","source":"billing:inv_123","customer":"cu_3f9a1c07b2e84d6a","amount":"100.00","asset":"USD","token":"rf1.acme.alice"}],"theirs":[{"type":"event","at":"2026-11-02T15:00:00Z","kind":"payment","source":"billing:inv_123","customer":"cu_3f9a1c07b2e84d6a","amount":"90.00","asset":"USD","token":"rf1.acme.alice"}]}},{"name":"verify_statement","title":"Recompute a statement","description":"Recomputes a statement's root and totals from its accrual lines, and reads its signoffs. With parties it tests their signatures. With proof it tests one accrual's inclusion against the root. It reports E42, E43, E44 and E45. A Merkle root shows what a statement holds. It does not show the statement is complete.","required":["statement"],"read_only":true,"example":{"statement":{"referrals":3,"type":"statement","id":"st_80266f03ea27315daf4bc2d5","at":"2026-12-01T00:00:00Z","program":"rp_13ea676cb997f5d1c8f87613","payee":"pt_aaec3c36d029aae40dbccece","start":"2026-11-01T00:00:00Z","end":"2026-12-01T00:00:00Z","rev":0,"by":"pt_921d8eb87f31deb6958d5a9e","terms":["sha256:2599b91bdce46e0821798e91827778c24947fdbebef0a00f7083a8002756766d"],"count":1,"root":"sha256:09302942b3dadca1c062c7bbb3eed090c99221314b805fb9bc59ce6ab9bfc982","totals":[{"asset":"USD","opening":"0.00","earned":"11.00","true_ups":"0.00","reversed":"0.00","adjusted":"0.00","net":"11.00","paid":"0.00","closing":"11.00","unverified":"0.00","held":"11.00","payable":"0.00","carried":false}]},"accruals":[{"referrals":3,"type":"accrual","id":"ac_b0f023a1d4ea1ced3f02a692","at":"2026-11-02T15:00:00Z","program":"rp_13ea676cb997f5d1c8f87613","terms":"sha256:2599b91bdce46e0821798e91827778c24947fdbebef0a00f7083a8002756766d","event":"ev_7192e36d2a1b4669849c3b4d","touch":"tc_5a1d426b0c1ca8512d1039eb","rule":"revenue_share","kind":"earn","payee":"pt_aaec3c36d029aae40dbccece","amount":"11.00","asset":"USD","payable_at":"2026-12-02T15:00:00Z","referrer":"pt_aaec3c36d029aae40dbccece","share_ppm":1000000,"group_ppm":1000000,"pot":"11.00","base":"100.00","rate":"11%","split_ppm":1000000,"clawback_until":"2027-01-01T15:00:00Z","notes":["disclosure_unstated"]}],"proof":{"accrual":"ac_b0f023a1d4ea1ced3f02a692","leaf_index":0,"tree_size":1,"path":[]}}},{"name":"audit_touches","title":"Look for patterns worth a look","description":"Scans records for patterns such as self-referral candidates, very fast conversions, injected initiators, loops, wash patterns, usage overlaps and backdated tokens, as flags F01 to F14 with the ids behind each. A flag is worth a look. It is not a finding of fraud. Send program as well to get the reversal-rate flag.","required":[],"read_only":true,"example":{"program":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n","as_of":"2026-12-31T00:00:00Z","records":[{"type":"touch","token":"rf1.acme.alice.k3v9x2.tnvqzy.dcw.n.-"},{"type":"event","at":"2026-11-02T15:00:00Z","kind":"payment","source":"billing:inv_123","customer":"cu_3f9a1c07b2e84d6a","amount":"100.00","asset":"USD","token":"rf1.acme.alice.k3v9x2.tnvqzy.dcw.n.-"}]}},{"name":"simulate_program","title":"Run a program on a made-up scenario","description":"Writes the events a plain scenario implies, runs them through the same engine as any ledger, and returns earned, reversed and held per payee per month. It is labeled arithmetic on the inputs you send: not a forecast, and it reads no outside data. Limits: 1000 customers, 120 months, 32 referrers, 5000 events.","required":["program","as_of"],"read_only":true,"example":{"program":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n","scenario":{"customers":10,"monthly_amount":"100.00","months":12,"refund_pct":10,"referrers":2},"as_of":"2026-11-01T00:00:00Z"}},{"name":"explain_program","title":"Answer the twelve questions for a program","description":"Reads a program and answers the twelve questions at /framework.md in plain words. Each answer says whether the file states it, the format's default fills it, or nothing does, with the fix. It also returns what check_referrals finds. It reads only what you send, and it says nothing about whether a deal is fair or lawful.","required":["program"],"read_only":true,"example":{"program":"---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n"}},{"name":"compare_programs","title":"Run one scenario through several programs","description":"Runs your own made-up scenario through two to six programs, by the same engine, and returns what each computes, what is held, and how many of the twelve questions each leaves open. It doesn't rank them or call one best, and it holds no data on any program: you bring the terms. A fee must not change what you recommend to a customer.","required":["programs","as_of"],"read_only":true,"example":{"programs":["---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme\nat: 2026-10-30T00:00:00Z\n---\n# Acme partner program\n## Rules\n### revenue_share\n- on: payment\n- basis: percent\n- rate: 11%\n- of: amount\n- recurring.months: 12\n","---\nreferrals: 3\nkind: program\npayer: domain:acme.example\ncode: acme_flat\nat: 2026-10-30T00:00:00Z\n---\n# Acme flat program\n## Rules\n### first_payment\n- on: payment\n- basis: flat\n- amount: 70.00\n- asset: USD\n- once_per: customer\n"],"scenario":{"customers":10,"monthly_amount":"100.00","months":12,"refund_pct":10},"as_of":"2026-11-01T00:00:00Z"}},{"name":"scaffold_stack","title":"What your role does on day one","description":"Gives one role its minutes, steps, files, fields and snippets, and says what it gets when the other side has not adopted anything. Roles: saas_founder, mcp_or_skill_author, harness_team, partner_manager, crypto_team, marketplace, reseller_or_consultancy, finance_ops. With no role it lists them. Minutes are rough, and it writes nothing anywhere.","required":[],"read_only":true,"example":{"role":"saas_founder"}},{"name":"self_test","title":"Compare your outputs with the test vectors","description":"Compares an implementation's outputs with /vectors.json, level by level, as canonical JSON, and lists what differs and where. Results are your own. No level is a certification, there is no badge program, and no one to apply to. With no outputs it lists the vectors. It stores nothing.","required":[],"read_only":true,"example":{"level":"L2","outputs":{}}},{"name":"build_settings","title":"Write your settings into the skill","description":"Turns a preset and settings into the sections written at the top of REFERRALS.md. Every setting is a number or a fixed choice; the catalog is at https://referrals.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.","required":[],"read_only":true,"example":{"preset":"recommended"}},{"name":"whats_new","title":"What's new here, and what's next","description":"What changed on referrals.md and when, what is planned, when to check back, and the other .md sites. Pass since (a date) to get only newer entries, for example the updated date of the skill you have. Reads a list kept with the code; fetches nothing and stores nothing.","required":[],"read_only":true,"example":{"since":"2026-10-01"}}],"prompts":[{"name":"referrals","title":"REFERRALS.md","description":"The REFERRALS.md skill. Pass a preset or any setting to write your settings in. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree."},{"name":"read-this-deal","title":"Read this deal","description":"Bring: A partner agreement, terms page or email. Get: The twelve answers, what's left open, a worked example, the questions to ask, and the deal as a program file."},{"name":"compare-these-programs","title":"Compare these programs","description":"Bring: Two or more programs' terms, and your own numbers. Get: One table on one footing: what each computes, what's held, what can be taken back, and what would change the order."},{"name":"design-my-program","title":"Design my program","description":"Bring: Your price and what you can afford, over five short questions. Get: Three structures with their cost and abuse risk, then a program file, partner terms and a disclosure line."},{"name":"wire-my-repo","title":"Wire my repo","description":"Bring: Your repo. Get: A map of where referrals get lost, then capture, event lines and a check, on your yes."},{"name":"audit-my-agent","title":"Audit my agent","description":"Bring: Your prompts, skills and tool descriptions. Get: Where pay could go undisclosed or a page could steer it, with fixes, a policy file and AGENTS.md lines."},{"name":"reconcile-these-numbers","title":"Reconcile these numbers","description":"Bring: A partner's statement and your own export. Get: Every row sorted into match, differ, only mine, only theirs, the difference by cause, and a draft note."},{"name":"who-should-pay-me","title":"Who should pay me?","description":"Bring: Your repo, docs and logs. Get: Who you already send customers to, with the evidence, and a draft partner ask for each."}],"resources":[{"uri":"https://referrals.md/referrals.md","name":"REFERRALS.md","title":"REFERRALS.md skill"},{"uri":"https://referrals.md/changelog.md","name":"changelog","title":"REFERRALS.md changelog: what's new and what's next"},{"uri":"https://referrals.md/api/v1/settings","name":"settings","title":"REFERRALS.md settings catalog"}],"example_note":"The values in the examples are made up. Send your own.","page":"https://referrals.md/mcp in a browser shows this list with examples you can run.","docs":"https://referrals.md/#install","disclaimer":"Use at your own risk. referrals.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is legal, tax, accounting or financial advice, and computed amounts do not say what anyone owes: your contract decides that. referrals.md never receives, holds, sends or routes money or crypto, keeps your records, runs a referral program or signs anything. Check everything yourself before you act on it.","terms":"https://referrals.md/terms"}