BagOS

BagOS 🚦 An MCP server that lets an AI assistant trade on Solana — and signs nothing until you say so.

🚀 Install

npx bagos-mcp-server

Claude 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-server

Restart the client, then ask it: *"show me the top Bags creators"*. The server prints a configuration report to stderr on startup; if something is missing it tells you which variable and why.

An API key alone gives you 8 of the 11 read tools. Three of them — bags_heartbeat, bags_get_claimable_fees and bags_authenticate — report on *your* wallet, so they also need BAGS_KEYPAIR_PATH and will error without it. Writes stay off until you configure them (Getting Started).

🔒 Why this is safe to hand an assistant

• Nothing signs on the first call. A write tool answers with a preview and a single-use token fingerprinted to those exact arguments; nothing reaches the chain until you call again with it.
• Hard SOL caps. 0.1 per transaction and 1 per session by default, refused before the Bags SDK is called.
• Devnet by default. Writes are mainnet-only, so an unconfigured install cannot spend real money.

Full threat model, disclosure policy and the limits of each control: [.github/SECURITY.md](.github/SECURITY.md).

⚠️ If you used 1.x — v2.0.0 corrected a serious defect

v2.0.0 corrects a serious defect. In 1.x the write tools built

transactions, discarded them, and reported success — nothing was ever signed

or submitted. If you used 1.x and believed a trade or claim executed, it did

not. See CHANGELOG.md.

2.x is live on npm and is what npx bagos-mcp-server installs — see the

latest release. Every release ships with

npm provenance —

the tarball is cryptographically attested to this repository and the commit that built it.

1.x is deprecated on npm. If you are still on it, upgrade.

---

📦 Where it's listed

---

💡 The Problem & Solution

The Problem

An MCP server that can move money gives an AI assistant a signing key. The assistant decides, and the transaction is already on chain by the time a human reads about it. Nothing in the protocol makes the model pause, and nothing bounds what a single misunderstood instruction can spend.

The Solution

Bags is a Solana token launchpad whose defining feature is creator fee sharing: a token's trading fees are split on-chain between the people who launched and promote it, claimable at any time. That makes "who earns from this token, how much is claimable, and claim it" a real workflow — and the one BagOS automates.

BagOS lets an AI assistant read Bags/Solana token data and — with explicit confirmation — execute swaps and claim creator fees from your wallet. Writes are off unless you configure them, they are mainnet-only, and the first call to a write tool signs nothing: it returns a preview and a single-use token that only authorizes the exact arguments it was issued for.

---

🏗️ Architecture & Tech Stack

Every write goes through this:

token gate → spend caps → confirmation → simulate → sign → send → confirm

bags_prepare_token_metadata reserves a mint and uploads metadata. Completing a launch also requires a Meteora fee-share config, whose fee-claimer split has to be your decision — so this server does not implement that step rather than guessing at it. Finish the launch at bags.fm.

---

🔐 Write Tools & Spend Controls

Writes are off unless you configure them, and they are mainnet-only.

Bags has no devnet deployment. Its API endpoint and its Meteora/fee-share program IDs are all mainnet. This server nonetheless defaults to devnet, so an unconfigured install cannot spend real money. Calling a write tool on devnet returns an explanation, not a cryptic program error.

The first call to a write tool signs nothing. It returns a preview and a single-use token:

⚠️  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"

The token is a fingerprint of the tool name plus the exact arguments, so one issued for a 0.01 SOL swap cannot authorize a 10 SOL one. It expires in five minutes and is consumed on every outcome, so it cannot be replayed.

On success you get a real signature and explorer link — never a success message for a transaction that did not land.

Set BAGS_ALLOW_UNCONFIRMED=true to skip the preview. Spend caps still apply.

The caps only bind on SOL. A swap whose input is some other token cannot be valued in SOL, so no cap can limit it. Those swaps are refused by default; set BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS=true to permit them, and the preview will say plainly that the trade is uncapped.

---

⛓️ Live Deployment

A real transaction, landed through the production write path and re-fetched from the chain rather than trusted from a return value:

Reproduce it yourself with npm run proof:devnet — it funds a throwaway keypair from the faucet, pushes a transfer through the same simulate → sign → send → confirm path the write tools use, then re-fetches the signature from the chain. A function returning success is a claim; a signature you can open on an explorer is evidence. Full method in DEMO.md.

---

📊 Engineering Rigor

418 tests. The bypass tests around the spend caps and the confirmation step are load-bearing; treat a change there as a security change. They were checked by hand against deliberate mutations: deleting the cap guard, the confirmation check, the decimals lookup, or the spend recorder each makes the suite fail. That was a manual exercise, not an automated mutation-testing stage — there is no mutation config in this repo to re-run.

| Real default path | ✅ | No kill-switch flag in any documented command. USE_MOCK_DATA defaults off; when on, it affec