> ## Documentation Index > Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools > Every tool a connected agent gets on the Sumvin MCP connector, grouped by what it's for. A connected agent doesn't see everything Sumvin can do. It sees a fixed set of tools, chosen for the account holder's own errands and identity — never budgets, card controls, or anything that isn't the agent's to touch. The account holder manages those in the Sumvin app or the CLI instead. These tools are visible before an account is connected, so a client can list them as soon as the connector is added. Each tool declares the OAuth scope it needs, and a client uses that to ask the person to connect their Sumvin account the first time a tool needs it. Calling a tool before then returns a refusal that asks the client to connect the account. Someone with no Sumvin account yet sees the same tools, but every one of them needs an account first. Calling any of them returns a refusal that carries a sign-up link to hand to the person — see [Refusals](/reference/mcp/refusals). Each tool is either **Read** (returns information, changes nothing) or **Write** (starts or changes something). Most tools work for anyone with an account; a few need the account holder's identity to be verified first — those are marked below. ## Getting started ### onboarding\_status Read Show where the account holder has got to in setting up their account: which steps are done, which are next, and how far the key they sign with has got. Reading it changes nothing. Each stage reads `current` (the one to do next), `pending` (still ahead), `submitted` (handed in and waiting on a review), `completed`, or `skipped` (waived for this account). The identity stage can also read `retry`: the reviewer asked for the ID capture again. The account holder retakes it on the verification page they already have open, and their phone stays confirmed. If that page is closed, call `kyc_start` for a fresh link. Or the identity stage can read `rejected`: the reviewer has made a final decision not to verify the account holder. Trying again won't change it, so your agent doesn't call `kyc_start` for them. It tells them plainly that their identity couldn't be verified and points them to Sumvin support. `recorded_at` is when the decision was made, and it stays final unless a reviewer later approves them. Each stage also carries `recorded_at`: when it reached its status, in epoch milliseconds. It's null while the stage is open, or when no time was recorded. While the account holder still owes a signing key, the answer carries `signing_key_url`: the browser page where they create and bind that key themselves. Your agent hands it to them to open; there's nothing it can call to bind the key on their behalf. **Try asking your agent:** "Where am I up to with Sumvin?" ### kyc\_start Write Get the link that starts identity verification, and hand it to the account holder. It's a single browser trip: they verify a phone number, then their identity, in one sitting. If they're already verified, this says so instead of handing over a link. If the reviewer has made a final decision not to verify the account holder, the call is refused with the code `KYC-403-005` and no link is made. Starting again won't change the decision, so your agent tells them plainly and points them to Sumvin support instead of retrying. **Try asking your agent:** "Help me get verified with Sumvin." ## Identity ### sigil\_show Read Show the account holder's Sigil — their verified identity. Reports whether it's been issued yet, is being issued right now, or hasn't started. Not having one yet is a normal answer, not a problem. **Try asking your agent:** "Show me my Sigil." ### agent\_identity\_show Read Show this connection's own identity: its registration status, and whether it's linked to the account holder's Sigil yet. Answers only for the connection asking — it can't see any other agent the account holder has connected. **Try asking your agent:** "What's your identity under my Sigil?" ## Stamped Mandates A Stamped Mandate is a signed authorisation for what one agent may do. These tools cover the spending kind — how much an agent may spend, and until when — because that's what the mandate tools support today. These tools still show their internal name, `pint`, in two places: it's the same object as a Stamped Mandate, and the rename is in progress. ### mandate\_request Write · Needs verification Ask the account holder to authorise spending, and get the link that lets them review and sign it. This doesn't grant anything by itself — only the account holder can sign, on their own page, and an agent can't do that for them. Needs a wallet and a verified identity first; if either is missing, this says which one and where to go next. **Try asking your agent:** "Set up a spending limit of \$50 for groceries this week." ### mandate\_status Read Check what the account holder decided about a mandate that was requested: still waiting, signed, declined, or expired. There's no notification when they decide — call this again after giving them time to look. **Try asking your agent:** "Did I approve that spending limit yet?" ### mandate\_verify Read Check a Stamped Mandate someone else has presented: what it permits, up to how much, and whether it still stands. Use this before acting on a mandate a counterparty shows you — an identifier alone proves nothing, and a mandate can be withdrawn at any time after it's granted. **Try asking your agent:** "Check whether this mandate is still valid before we go ahead." ### mandate\_capacity\_query Read Read what's left to spend under the Stamped Mandate authorising an errand: its limit, what's settled, what's held by spending in flight, and what remains. **Try asking your agent:** "How much is left on the mandate for my grocery errand?" ### pint\_query Read List the Stamped Mandates issued to the account holder. Filter by status or by identifier. **Try asking your agent:** "Show me all my active spending limits." ### pint\_revoke Write Permanently withdraw a Stamped Mandate. This can't be undone — anything relying on it to spend stops being able to, immediately. Find the one to revoke with `pint_query` first. **Try asking your agent:** "Revoke the spending limit I set up for groceries." ## Payment methods An errand pays with the card the account holder has added. These tools let an agent check that a card is ready and, when it isn't, send the account holder to the page where they add one. The card is always entered on that page, by the account holder — never in the conversation. ### payment\_method\_query Read List the cards the account holder has added and whether each is ready. A card can pay for an errand only once it shows as verified. Card numbers are never shown — only the last four digits. **Try asking your agent:** "Is my card ready for purchases?" ### payment\_method\_add Read Get the link to the page where the account holder adds the card their errands pay with, along with the cards they already have. The tool changes nothing itself. A card can be added once identity verification has finished; wait for it to show as verified before starting an errand. **Try asking your agent:** "I need to add a card before you buy anything for me." ## Errands An errand is a long-running purchase task the account holder asked their agent to make, run within a Stamped Mandate. ### errand\_create Write Start a new errand from what the account holder asked for, in their own words, with the most they'll spend: `constraints.max_total` (whole purchase) or `constraints.max_price` (per item), plus `constraints.currency`. Without a spend limit the errand isn't created (`spend_limit_required`). Starting an errand doesn't authorise any spending on its own: the account holder asks, signs, and only then does Sumvin search, check the merchant, watch for their conditions, and settle the purchase. **Try asking your agent:** "Reorder my usual coffee beans." ### errand\_action Write Act on an errand that's already running: answer a question it's waiting on, or cancel it. Signing an errand isn't available here — only the account holder can sign it, before it searches, on their own page. A pick found within the bounds they signed is then bought without asking them again. **Try asking your agent:** "Cancel that coffee order — I changed my mind." ### errand\_query Read Read the account holder's errands: what they are, and where each one stands. Filter by status or by identifier. **Try asking your agent:** "What's the status of my coffee order?" ### errand\_events\_query Read Read one errand's history: what happened, and when, oldest first. **Try asking your agent:** "What's happened so far with my coffee order?" ## Account ### account\_query Read Read the account holder's linked accounts. **Try asking your agent:** "What accounts do I have linked?" ### wallet\_query Read Read the account holder's wallets. **Try asking your agent:** "Show me my wallets." ### transaction\_query Read Read the account holder's transactions: what they spent, where, and when. When the agent presents a Stamped Mandate that signs `transactions:read` with a date range, the results are held inside that range, whether or not the question names dates, and a date outside it is refused. Signing in to the connector alone carries no date range. See [Limit reads to a date range](/concepts/mandates/scopes#limit-reads-to-a-date-range). **Try asking your agent:** "What have I spent this week?" ### asset\_query Read Read reference data for the currencies and assets Sumvin supports. Not scoped to the account holder — this is general information, not a personal record. **Try asking your agent:** "What currencies does Sumvin support?" ## Server ### server\_info Read · No account needed Report the build identity of the Sumvin server this connection has reached. Useful for confirming the connection is live before trying anything else. **Try asking your agent:** "Are you connected to Sumvin?" ### sumvin\_guide Read · No account needed Load a Sumvin guide: what Sumvin is, how to use its tools safely, and the reference file for each task. Pass `name` (`sumvin-sigil`, or `sumvin-sigil-onboard` for someone without an account yet), and `file` for one of its reference files. It's the same content a host that supports skills installs from `skill://sumvin-sigil`, so a host that only calls tools still gets it. **Try asking your agent:** "How do you use Sumvin?" ## In the Sumvin app and CLI These tools answer only when the account holder's own Sumvin app or the Sumvin CLI calls the server. A connected agent never sees them: calling one from a connector is refused, and the refusal says to manage it in the app or the CLI instead. ### allocations\_query Read List what has been spent against an errand's mandate, newest first, and whether each spend has settled. ### budget\_query Read Read the account holder's budgets, by name, type, or the kind of spending they cover. ### budget\_upsert Write Create a budget, or replace one in full. ### budget\_delete Write Delete a budget. It stops counting spending; its history is kept. ### card\_query Read Read the account holder's cards and their current status. ### card\_action Write Freeze a card, or unfreeze it. Neither cancels the card or touches payments already made. ### rule\_query Read Read the account holder's rules. ### rule\_upsert Write Create a rule, or replace one in full. ### rule\_delete Write Delete a rule. It stops applying from then on. ### strategy\_list Read List the strategies the account holder can enrol in. ### user\_strategy\_query Read Read the strategies the account holder is enrolled in. ### user\_strategy\_create Write Enrol the account holder in a strategy, after checking that whatever it needs is in place. ### user\_strategy\_update Write Pause or restart an enrolment, or adjust its settings. ### user\_agent\_task\_query Read Read the runs queued or completed for the account holder's strategies. ### user\_agent\_task\_manage Write Queue a strategy run, or cancel one that hasn't started. ### wallet\_update Write Rename a wallet, or make it the account holder's main one. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.