# MCP tools

> Every tool of the MCP server with what it does, who may call it and its inputs, as tools/list returns them.

The server at `https://mcp.402lounge.com/mcp` speaks Streamable HTTP and needs no key to connect. Calling a tool costs nothing. This page is written from what the server registers, so it names the same tools as `tools/list`.

Tools that need an account also take `session_token`, `proof` and `client`, the sign-in fields from [Accounts and sign-in](https://402lounge.com/docs/accounts.md#ways-to-prove-who-you-are). A client that sends `Authorization: Bearer lg_...` needs none of them. The lists below leave these three fields out.

A tool that fails returns `isError: true` with the error body of [Errors and limits](https://402lounge.com/docs/errors.md) in `structuredContent`.

## Account

### lounge.requirements

**What you need to join.** Rules, prices, the current terms and the exact sentences you will sign. Free, no account.

Who: No account.

Inputs: none.

### lounge.terms

**Current terms.** Versions, hashes and links of the terms and the privacy notice. With accept: true you confirm a new version: first call returns a challenge, second call with proof {message, signature} records it.

Who: No account. Accepting a new version: the agent itself.

Inputs:

- `accept` (boolean, optional)

### lounge.signup

**Create your account.** Free. Your account is a company from the first call, named after you until company.update adds the legal data. With invite_code you join an existing company instead. Proves your wallet with a signature: first call returns a challenge, second call with proof {message, signature} creates the account. Wallets that cannot sign pay 0.001 USDC over HTTP instead (pay_instead in the answer), once payments are open.

Who: A wallet that signs, or pays 0.001 USDC.

Inputs:

- `name` (string, required): Your name as an agent, unique inside your company, e.g. "Research"
- `invite_code` (string, optional): From company.invite, to join that company
- `email` (email, optional): Optional: where documents and notices of your new company go. Ignored with invite_code.
- `address` (string, optional): Your wallet address, so the challenge comes back as a finished message
- `provider` (string, optional): awal, cdp, viem, other
- `accept` (object {terms, privacy, business}, required)

### lounge.me

**You and your company.** Who you are (agent and role), your company with its agents, people and level, its wallets, your apps, terms state and pending notices.

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### lounge.agent.update

**Rename yourself.** Your name inside the company, 1 to 40 characters, unique in the company. Company data lives in company.update.

Who: The agent itself.

Inputs:

- `name` (string, required)

### lounge.wallet.add

**Add a wallet.** The new wallet proves itself: first call returns a challenge for it, second call with wallet_proof {message, signature} adds it. It belongs to your company and you operate it. How many follows the plan: Free 1, Books 5 per agent and 15 in all, Books for teams without limit.

Who: Any agent.

Inputs:

- `address` (string, required)
- `provider` (string, optional)
- `wallet_proof` (object {message, signature}, optional)

### lounge.wallet.remove

**Remove a wallet.** Your own wallets (admins: any wallet of the company). Not the one you sign in with, and never your last one. Sessions made with that wallet end. Its receipts stay.

Who: Agents their own wallets. Admins and owners any.

Inputs:

- `address` (string, required)

### lounge.wallet.primary

**Set your sign-in wallet.** The wallet you sign in with. It has to be assigned to you.

Who: The agent itself.

Inputs:

- `address` (string, required)

### lounge.wallet.list

**Wallets.** All wallets of your company, each with the agent that operates it. mine: true lists only yours.

Who: Anyone in the company.

Inputs:

- `mine` (boolean, optional)

### lounge.session

**Session tokens.** create: a new lg_ token (needs a signature or an existing token). list and revoke manage them.

Who: The agent itself.

Inputs:

- `action` ("create", "list", "revoke", required)
- `session_id` (id, optional)

### lounge.apps

**Connected apps.** Which clients this agent has used. deactivate ends their sessions, activate turns them back on, disconnect forgets them.

Who: The agent itself.

Inputs:

- `action` ("list", "deactivate", "activate", "disconnect", optional, default "list")
- `app_client` (string, optional)

### lounge.notices

**Notices.** Terms changes, moderation decisions, deletion and security notes, for you and for your company. ack marks one as read.

Who: Anyone in the company.

Inputs:

- `action` ("list", "ack", optional, default "list")
- `id` (integer, optional)
- `all` (boolean, optional)

### lounge.dashboard.link

**Dashboard link.** A one-time browser link (10 minutes) into your company's dashboard, signed in as you, for the human behind you.

Who: The agent itself.

Inputs: none besides the sign-in fields.

### lounge.account.export

**Export your data.** Everything 402lounge keeps about you as an agent off chain, as JSON. The company's books come from receipts.list and invoices.list.

Who: The agent itself.

Inputs: none besides the sign-in fields.

### lounge.account.delete

**Delete yourself.** Schedules your deletion as an agent in 7 days. cancel: true keeps you. Your wallets and receipts stay with the company. Needs a fresh signature with the delete statement (first call returns the challenge).

Who: The agent itself, with a fresh signature.

Inputs:

- `confirm` (true, required)
- `cancel` (boolean, optional)

## Receipts and register

### receipts.record

**Report a payment you made.** Call this after every x402 payment: the transaction hash from the PAYMENT-RESPONSE header plus the URL you paid. 402lounge matches it with the transfer on Base and writes a receipt with the seller from the register, the catalogue description and a provisional EUR value. Free.

Who: Any agent.

Inputs:

- `tx_hash` (string, required): The settlement transaction, 0x plus 64 hex characters
- `resource_url` (URL, optional): The URL you paid for (the 402 resource)
- `amount` (string, optional): What you paid, in USDC, e.g. "0.002"
- `description` (string, optional): What you bought, in your words. The seller's catalogue wins when it knows the URL.
- `pay_to` (string, optional): The payTo address from the payment requirements
- `network` ("base", "base-sepolia", optional)
- `payment_response` (string or object, optional): The raw PAYMENT-RESPONSE header, if you still have it

### receipts.list

**Your company's receipts.** Receipts of your company for one month (default: the current month, Europe/Berlin), newest first, each with the agent that paid. Totals per seller and per agent, and the reports still waiting for the chain. mine: true, agent_id or wallet narrow it.

Who: Anyone in the company.

Inputs:

- `month` (string, optional): Like 2026-10
- `status` ("verified", "listed", "unverified", optional): Only receipts with this seller status
- `limit` (integer, optional)
- `before` (integer, optional): Page: the smallest receipt id of the previous page
- `mine` (boolean, optional): Only the receipts of wallets you operated
- `agent_id` (id, optional): Only one agent of the company
- `wallet` (string, optional): Only one paying wallet

### receipts.get

**One receipt.** A single receipt of your company by id or transaction hash.

Who: Anyone in the company.

Inputs:

- `id` (string, required): Receipt id or 0x transaction hash

### register.lookup

**Who is behind this wallet?.** Wallet in, seller out: the listing that owns a payTo address, its verification level, its paid endpoints and the last health check. Free, no account. Call it before you pay someone new.

Who: No account.

Inputs:

- `address` (string, required): A payTo address on Base

## Company

### company.get

**Your company.** Legal data, VAT status, tier and level, what is missing for the next tier, its agents with this month's spending, its people and your role.

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### company.update

**Fill in or change the company data.** Admins only. Your account starts as a company named after you. Add name, legal_form, address_line1, postal_code, city, country and email to make it a company that gets monthly vouchers, plus a VAT id (checked against VIES at once) for invoice_ready. Any subset works, and the answer lists what is still missing.

Who: Admins and owners.

Inputs:

- `name` (string, optional): Legal name of the company, without the legal form
- `legal_form` (string, optional): GmbH, UG, AG, e.K., Inc., ...
- `address_line1` (string, optional)
- `address_line2` (string, optional)
- `postal_code` (string, optional)
- `city` (string, optional)
- `country` (string, optional): ISO 3166 two-letter code, e.g. DE
- `vat_id` (string, optional): VAT id in the format of its country, like DE123456789 or ATU12345678 (GET /v1/countries). EU numbers are checked against VIES
- `tax_number` (string, optional)
- `vat_status` ("vat_id", "tax_number", "small_business", "exempt", "not_registered" or null, optional): How the company stands with VAT: vat_id, tax_number (registered, VAT id still to come), small_business (§ 19 UStG) exempt (only VAT-exempt sales) or not_registered (no VAT registration, the USA or another country without VAT). Decides the tax note on its documents
- `skr` ("SKR03", "SKR04", "OWN", optional): Chart of accounts for exports. OWN takes own_accounts
- `own_accounts` (object {expense, clearing, usdc} or null, optional): With skr OWN: the expense, clearing and USDC holding accounts of your chart, 4 to 8 digits
- `currency` (string, optional): The currency amounts are shown in, next to USDC: EUR (default, the currency of the documents), USD, or any currency with an ECB reference rate
- `fx_method` ("ecb_daily", optional): How USDC becomes EUR on documents. Today only ecb_daily (ECB reference rate of the payment day)
- `email` (email, optional): Where documents and notices go. A code confirms it

### company.vat_check

**Re-check the VAT id.** Asks VIES again and updates the tier. Admins, owners and finance.

Who: Admins, owners and finance.

Inputs: none besides the sign-in fields.

### company.email

**The company email.** Where documents and notices go. start sets the address and mails a 6-digit code, confirm checks it, remove clears it (only while the account has no company data). Admins only.

Who: Admins and owners.

Inputs:

- `action` ("start", "confirm", "remove", required)
- `email` (email, optional)
- `code` (string, optional)

### company.invite

**Invite another agent.** Admins only. A code valid for seven days. A new agent signs up with lounge.signup {invite_code}, an agent with its own account calls company.join {code} and brings its wallets and receipts.

Who: Admins and owners.

Inputs: none besides the sign-in fields.

### company.join

**Join a company.** With an invite code. Works while your own account has no company data, no vouchers and no other agents: your wallets, receipts and reports move into that company and your own account goes away. You join as an agent, and an admin there can make you admin.

Who: An agent with an account of its own.

Inputs:

- `code` (string, required)

### company.agents

**Agents of your company.** Every agent with its role, its wallets and what it paid this month (receipts, USDC, EUR).

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### company.agent.update

**Rename an agent or change its role.** Admins change any agent, an agent may rename itself. role is admin or agent. The company always keeps an admin or an owner.

Who: Admins and owners. An agent may rename itself.

Inputs:

- `agent_id` (id, required)
- `name` (string, optional)
- `role` ("admin", "agent", optional)

### company.agent.remove

**Remove an agent.** Admins only. Schedules the agent's deletion in 7 days. Its wallets stay with the company, unassigned, and its receipts stay in the books.

Who: Admins and owners.

Inputs:

- `agent_id` (id, required)

### company.wallet.assign

**Move a wallet to another agent.** Admins only. agent_id null leaves the wallet unassigned. Receipts already written keep the agent that paid, new ones get the new agent. Sessions of the previous agent made with that wallet end.

Who: Admins and owners.

Inputs:

- `address` (string, required)
- `agent_id` (id or null, required)

### company.wallet.label

**Name a wallet.** A name for the company's own lists, e.g. "Research budget". Agents may name their own wallets, admins any. label null clears it.

Who: Agents their own wallets. Admins and owners any.

Inputs:

- `address` (string, required)
- `label` (string or null, required)

### company.members

**People in your company.** list shows them. invite adds a person by email with a role: owner (everything), finance (documents, VAT check, plan), adviser (reads and exports, changes nothing, for a tax adviser), viewer (reads). They sign in by email link. An address that is in another company already keeps its login and gets this company next to the others. role changes a role, remove takes someone out. Admins and owners only, except list.

Who: Anyone in the company lists. Admins and owners change.

Inputs:

- `action` ("list", "invite", "role", "remove", optional, default "list")
- `email` (email, optional)
- `role` ("owner", "finance", "adviser", "viewer", optional)
- `member_id` (id, optional)

### company.requests

**The board: requests between people and agents.** Where the tax adviser or the team ask for things, like a receipt that is missing or a purchase nobody described. list shows open ones (status: done or all for more), show one with its answers (request_id), ask writes one (title, body, optional month like 2026-10 and receipt_id), answer replies (request_id, body) and opens it again, done and reopen change its status, delete takes it back. A new request mails the people who keep the books, an answer everybody in the thread. Whoever reads the receipts may use it.

Who: Whoever reads the receipts. Who asked, owners and admins delete.

Inputs:

- `action` ("list", "show", "ask", "answer", "done", "reopen", "delete", optional, default "list")
- `status` ("open", "done", "all", optional)
- `request_id` (id, optional)
- `title` (string, optional)
- `body` (string, optional)
- `month` (string, optional)
- `receipt_id` (integer, optional)

### company.close

**Close the company.** Admin agents and the owner. Closes the company in 30 days: name confirms it with the company name. Until then everything can be read and the export works (GET /v1/company/export), calls that write are refused with company_closing. Then agents, people, sign-ins, sessions and wallets are removed. Receipts and issued documents stay locked until their retention period ends. cancel: true keeps the company. now: true with export_kept: true closes at once and deletes the receipts and documents too, after you downloaded the export. Documents in a seller's name stay with the seller.

Who: Admins and owners.

Inputs:

- `name` (string, optional): The company name, as confirmation
- `cancel` (boolean, optional)
- `now` (boolean, optional): Close at once and delete everything
- `export_kept` (boolean, optional): With now: you downloaded the export and keep the records yourself

## Documents

### invoices.list

**Your company's documents.** Monthly vouchers per seller (and later invoices), newest first. Optional month like 2026-10.

Who: Anyone in the company.

Inputs:

- `month` (string, optional)
- `limit` (integer, optional)

### invoices.get

**One document.** The full document as JSON, by id or number, with where its archived files lie and their sha256. The PDF is at /v1/invoices/{id}/pdf with your session token.

Who: Anyone in the company.

Inputs:

- `id` (string, required)

### invoices.issue

**Issue the documents for a month.** Admins, owners and finance. Runs by itself every night for last month. Call it for an older finished month or after a cancellation. One document per seller: the monthly overview on Free, the voucher with the tax note on Books. Payments that arrive after a document get a supplement. Pairs with receipts that lack a EUR rate are skipped and listed. Needs the company data and a confirmed email (tier company).

Who: Admins, owners and finance.

Inputs:

- `month` (string, optional): Finished month, default: last month

### invoices.draft

**The month so far.** Drafts of the documents the month would get today, one per seller, with lines, totals and the tax case. Nothing is stored and there is no number. Default: the current month (Europe/Berlin). The PDF of a draft is at /v1/invoices/draft/pdf?month=&seller=.

Who: Anyone in the company.

Inputs:

- `month` (string, optional)

### invoices.cancel

**Cancel a document.** Admins, owners and finance. Issues a cancellation for a document, with your reason. The original keeps its number and turns to cancelled. Its payments are open again, so invoices.issue for that month (or the nightly run for last month) puts them in a new document.

Who: Admins, owners and finance.

Inputs:

- `id` (string, required): Id or number of the document
- `reason` (string, required)

## Directory

### directory.search

**Find a seller in the directory.** Services that take x402 payments, with their level (0 listed, 1 wallet verified), what they offer (MCP, .well-known/x402, llms.txt) and a link. Search by name, description or host. filter: all, verified or mcp. sort: level, new or name. A booked sponsored place stands in sponsored, marked as such, and never changes the order or a level. Free, no account.

Who: No account.

Inputs:

- `q` (string, optional): Words to look for, e.g. "on-chain data"
- `filter` ("all", "verified", "mcp", optional)
- `sort` ("level", "new", "name", optional)
- `limit` (integer, optional)
- `offset` (integer, optional)

### directory.get

**One listing.** A listing with its wallets (network and level), what its calls cost, other networks it takes and its links. Company and location show from level 2 on. Free, no account.

Who: No account.

Inputs:

- `slug` (string, required): The listing slug, e.g. glassnode

### directory.claim

**Claim your listing.** Admin agents and owners. A wallet the listing names proves the service is your company's: first call returns a challenge for that wallet, second call with wallet_proof {message, signature} signed by it claims the listing. The wallet moves to level 1 and payments to it name the listing on receipts. A listing your company holds takes more wallets the same way.

Who: Admins and owners, with a signature of the listing's wallet.

Inputs:

- `slug` (string, required): The listing slug, e.g. glassnode
- `address` (string, required): A payTo wallet of the listing
- `wallet_proof` (object {message, signature}, optional)

### directory.preview

**Read a paid URL for a new listing.** We call one paid URL once without paying, read its 402 answer and show the listing it would make: name, description, price, logo and the wallet you get paid on. Says so when the host or the wallet is listed already, then claim that listing instead.

Who: Anyone in a company.

Inputs:

- `url` (string, required): One https URL that answers 402 Payment Required

### directory.submit

**List your service.** Admin agents and owners. Puts the service behind one paid URL into the directory on level 0, under your company: its payTo wallet on Base, the call and its price from the 402 answer. contact_email is only for us, never shown. Then prove the wallet with directory.claim for level 1.

Who: Admins and owners.

Inputs:

- `url` (string, required)
- `contact_email` (email, required)

## Plans and billing

### billing.get

**Plan, limits and usage.** Your company's plan with its period and end, its limits (null means no limit), what it uses this month (transactions, agents, wallets), whether the one-time 20 % over the limit is used, whether the month is locked, the archive (keeps receipts and documents without a paid plan, archive) and what happens to them without either (retention).

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### billing.checkout

**Choose a plan.** Admin agents, the owner and finance. A checkout link at Polar for Books or Books for teams (plan + period), monthly or yearly (a year costs ten months), or for the archive (archive: month or year, €5 a month or €50 a year), which keeps receipts and documents of a company without a paid plan. Polar is the seller: it charges, handles VAT, issues the invoice and renews until cancelled. The invoices are in Polar's customer portal (billing.portal). Hand the link to a person of your company. It starts once Polar confirms the payment.

Who: Admins, owners and finance.

Inputs:

- `plan` ("books", "teams", optional)
- `period` ("month", "year", optional)
- `archive` ("month", "year", optional): The archive instead of a plan, monthly or yearly

### billing.portal

**Billing portal.** Admin agents, the owner and finance. A link to Polar's customer portal: payment method, invoices, change or cancel the plan.

Who: Admins, owners and finance.

Inputs: none besides the sign-in fields.

### sponsor.get

**The sponsored place.** Your company's sponsored places with status and dates, and whether the place is free. One sponsor at a time, first in the directory and in directory.search, marked Sponsored, never changing the order or a level. 49 € for one month, paid once.

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### sponsor.checkout

**Book the sponsored place.** Admin agents and the owner of the company the listing belongs to. A checkout link at Polar for one month of the sponsored place, 49 €, paid once, nothing renews. The month starts once Polar confirms the payment. While your place runs, the next month you book starts when it ends.

Who: Admins and owners of the company the listing belongs to.

Inputs:

- `listing` (string, required): Slug of your listing

### billing.quote

**Pay 402lounge in USDC.** Admin agents, the owner and finance. An offer to pay in USDC on Base: a plan (plan + period), the archive for a company without a paid plan (archive: month or year), one month of the sponsored place (sponsor: your listing slug) or the seller check for level 2 (seller_check: your listing slug, one year). The price is net in EUR, with VAT for your company and the ECB rate of the day, and the amount in USDC is unique for 30 minutes. Pay it yourself with your x402 client on pay_url, or a person sends exactly amount_usdc to pay_to. 402lounge sends an invoice. Nothing renews by itself. With quote_id only: the status of that offer, with the invoice once paid.

Who: Admins, owners and finance ask for an offer, anyone in the company reads one.

Inputs:

- `plan` ("books", "teams", optional)
- `archive` ("month", "year", optional): The archive, monthly or yearly
- `sponsor` (string, optional): Slug of your listing, for the sponsored place
- `seller_check` (string, optional): Slug of your listing, for the seller check
- `period` ("month", "year", optional)
- `quote_id` (id, optional): Read an offer instead of asking for one

### billing.invoices

**Invoices of 402lounge.** The invoices 402lounge issued to your company for payments in USDC, newest first, each with a PDF link (add ?lang=de for German). With id: one invoice with its full content. Plans bought through Polar get their invoice from Polar.

Who: Anyone in the company.

Inputs:

- `id` (id, optional)

## Sellers

### seller.get

**Your seller levels.** Your company as a seller: every listing with its level (0 listed, 1 wallet verified, 2 company verified, 3 invoicing), the company check and its steps, the seller profile (register entry, representative), the invoicing mandate and self-billing, and what is missing for the next level.

Who: Anyone in the company.

Inputs: none besides the sign-in fields.

### seller.profile

**Representative and register entry.** Admin agents and owners. What level 2 needs on top of the company data: the name of the person who acts for the company (representative_name, the role is optional). The commercial register court and number help the check but are optional, no_register: true where there is none. sole_proprietor: true when the company is one person, then show_name says whether the register may show the name.

Who: Admins and owners.

Inputs:

- `register_court` (string or null, optional): e.g. Amtsgericht Charlottenburg
- `register_number` (string or null, optional): e.g. HRB 123456
- `no_register` (boolean, optional)
- `representative_name` (string or null, optional)
- `representative_role` (string or null, optional): e.g. Managing director
- `sole_proprietor` (boolean, optional)
- `show_name` (boolean, optional)

### seller.check

**The company check of a listing (level 2).** Level 2 for a listing of your company on level 1: action start {listing} opens the check and returns its steps. The domain of the listing is proved by an email address at it: email {id, email} sends a code there, confirm_email {id, code} confirms it. Without a mailbox, add the DNS TXT record from the check instead (_402lounge.<host>, value 402lounge-verify=<token>). verify {id} runs the steps again (company data with the name of the person who acts for the company, VIES, the domain, EU sanctions list, payment). Once all pass, 402lounge approves it, then the listing is on level 2 for a year. checkout {id} gives the Polar link for 10 € a year, included in Books. get {id}, withdraw {id}.

Who: Admins and owners, checkout also finance, get anyone in the company.

Inputs:

- `action` ("start", "get", "verify", "email", "confirm_email", "checkout", "withdraw", required)
- `listing` (string, optional): The listing slug, e.g. glassnode
- `id` (id, optional)
- `email` (string, optional): email: an address at the domain of the listing
- `code` (string, optional): confirm_email: the six-digit code from the mail

### seller.mandate

**Invoicing mandate (level 3).** Admin agents and owners. get shows the mandate text (link, version, sha256) and whether it is signed. sign: first call returns a challenge, sign it with your wallet and call again with agreement_proof {message, signature}. Then, with a listing on level 2 and Books, buyers on level 3 get monthly invoices in your name (§ 14 (2) UStG), issued by 402lounge. revoke ends it at the end of the month.

Who: Admins and owners sign and revoke, an admin agent with a signature of its wallet, get anyone in the company.

Inputs:

- `action` ("get", "sign", "revoke", required)
- `agreement_proof` (object {message, signature}, optional)
- `confirm` (boolean, optional)

### seller.self_billing

**Self-billing agreement.** Admin agents and owners. Without a mandate, a company on level 2 can agree that its buyers on level 3 issue credit notes (Gutschriften) for what they paid, on any plan. get, sign (challenge, then agreement_proof), revoke (at the end of the month).

Who: Admins and owners sign and revoke, an admin agent with a signature of its wallet, get anyone in the company.

Inputs:

- `action` ("get", "sign", "revoke", required)
- `agreement_proof` (object {message, signature}, optional)
- `confirm` (boolean, optional)

### seller.invoices

**Documents in your name.** Invoices 402lounge issued in your name (L-2610-10427-01), credit notes your buyers issued to you (G-...) and their cancellations, newest first, each with its e-invoice. With id the whole document. PDF and XML: GET /v1/seller/invoices/{id}/pdf and /xml.

Who: Anyone in the company.

Inputs:

- `id` (string, optional)
- `month` (string, optional)
- `limit` (integer, optional)

### seller.invoices.cancel

**Cancel a document in your name.** Admin agents, the owner and finance. Cancels an invoice in your name or a credit note you received, with a reason: a cancellation in your number range follows, the original stays. The payments are open again and the next monthly run issues them anew.

Who: Admins, owners and finance.

Inputs:

- `id` (string, required)
- `reason` (string, required)