Every AI-initiated Solana spend:
gated, capped, confirmed on chain.
BagOS is an MCP server that lets an AI assistant read Bags/Solana token data and — only with explicit confirmation — execute swaps and claim creator fees. The first call to a write tool signs nothing. It answers with this:
⚠️ CONFIRMATION REQUIRED — nothing has been signed or sent.
Action: Swap 0.05 of So1111…1112
for EkJuyY…dBAGS
expect 4823917722 (min 4679199990)
slippage 3%
network 🔴 MAINNET — real funds
Spend: 0.05 SOL
Caps: 0.1 SOL/tx · 0/1 SOL used this session
To execute, call bags_execute_trade again with the identical arguments plus:
confirm: "kR3nT9xQm2vP"$ npx bagos-mcp-server
- 14 MCP tools
- 212 tests · 100% coverage
- 0.1 SOL/tx · 1.0 SOL/session caps
- v2.0.0 on npm, SLSA provenance
- Active in the MCP registry
The problem
An MCP server that can move money hands the model a signing key
The assistant decides, and the transaction is on chain before a human reads about it. Nothing in the protocol makes the model pause, and nothing bounds what one misunderstood instruction can spend.
BagOS treats that as the design problem, not a footnote. Reads are free. Every write has to pass a gate the model cannot talk its way around.
The mechanism
Seven stages between an instruction and a signature
Every write goes through this, in order. No stage can be skipped by the model — only by you, explicitly, in configuration.
The request lives in the amber box until you hand back the code — the preview at the top of this page is what stage three returns. The green box is the only place "success" is allowed to come from: a confirmed signature, re-fetched from the chain.
Fingerprinted to the arguments
The token is a fingerprint of the tool name plus the exact arguments. A token issued for a 0.01 SOL swap cannot authorize a 10 SOL one.
Single use, five minutes
It expires in 5 minutes and is consumed on every outcome — success, failure, or refusal — so it cannot be replayed.
Confirmed means on chain
On success you get a real signature and explorer link — never a success message for a transaction that did not land.
Safe by default
An unconfigured install cannot spend real money
Writes are mainnet-only, default is devnet
Writes are off unless you configure them, and they are mainnet-only. The server defaults to devnet, so an unconfigured install cannot spend real money.
Refuses to start on a network mismatch
If the RPC endpoint's cluster disagrees with BAGS_NETWORK, the server
refuses to start rather than sign mainnet transactions under a devnet banner.
Hard caps on every path
BAGS_MAX_SOL_PER_TX defaults to 0.1 SOL;
BAGS_MAX_SOL_PER_SESSION to 1.0 SOL. The caps apply
even if you disable the confirmation step.
What ships
14 tools, and the numbers behind them
212 tests
100% coverage — statements, branches, functions, lines — enforced in CI.
v2.0.0
"the write tools actually write" — released August 15, 2026, live on npm as bagos-mcp-server.
Registry-listed
Active in the official MCP registry as io.github.edycutjong/bagos.
The npm tarball is published from CI with SLSA provenance — cryptographically attested to this repository and the exact commit that built it. Not a claim: verify the attestation.
| Tool | Type | What it does |
|---|---|---|
bags_heartbeat | read | Server status and wallet reachability |
bags_get_token_analytics | read | Lifetime fee data for a token mint |
bags_get_creators | read | Top token creators by lifetime fees |
bags_get_trade_quote | read | Price quote for a swap. Does not trade. |
bags_get_claimable_fees | read | Fees currently claimable by your wallet |
bags_get_partner_stats | read | Partner config claim statistics |
bags_get_token_claim_stats | read | Per-creator claim totals — the royalty roster with amounts claimed |
bags_get_token_claim_events | read | The claim audit trail for a token, paginated |
bags_get_token_creators | read | Who shares a token's fees, and in what proportion |
bags_resolve_launch_wallet | read | Social handle (twitter/tiktok/kick/github) → fee-share wallet |
bags_authenticate | read | Verify wallet ownership via Ed25519 signature |
bags_prepare_token_metadata | gated | Creates token info + metadata. Does not launch a token. |
bags_execute_trade | write | Swap tokens. Signs and submits. |
bags_claim_fees | write | Claim creator/LP fees. Signs and submits. |
Why the pipeline ends at "confirm"
v1.x claimed success for transactions that never existed
This project's whole thesis is not overclaiming — so here is ours.
v1.x had a defect: the write tools built transactions, discarded them, and reported success. Nothing was ever signed or submitted. v2.0.0 fixes it — a write now returns success only after the confirmed signature is re-fetched from the chain. The full account is in the changelog; the release is named after the fix: v2.0.0 — "the write tools actually write".
Install
One command, or one config block
You need a Bags API key from dev.bags.fm — that alone enables the read-only tools. Writes stay off until you configure them.
Run it
Installs bagos-mcp-server@2.0.0 from npm — published from CI with SLSA provenance.
npx bagos-mcp-serverClaude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"bagos": {
"command": "npx",
"args": ["-y", "bagos-mcp-server"],
"env": {
"BAGS_API_KEY": "your-key-here"
}
}
}
}Claude Code
claude mcp add bagos --env BAGS_API_KEY=your-key-here -- npx -y bagos-mcp-serverRestart the client, then ask it: "check the bagos heartbeat". The server prints a configuration report on startup; if something is missing it tells you which variable and why. To enable writes — mainnet, keypair, gating token, caps — follow the write-tools guide in the README.