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.

📦 Where it's listed

Live Site Pitch Deck Run Receipts Security Policy Changelog

💡 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.

E2E browser tests and Lighthouse budgets are deliberately absent: this is a stdio/HTTP MCP server with no web UI, so both would measure nothing. The nearest end-to-end coverage is npm run demo, which drives five read tools — bags_heartbeat, bags_get_creators, bags_get_trade_quote, bags_get_partner_stats and bags_authenticate — over real MCP JSON-RPC against the live API. The remaining read tools are covered by unit tests only.

🚀 Getting Started

Prerequisites

You need a Bags API key from dev.bags.fm. That alone enables the read-only tools. For trading and fee claims you also need a Solana keypair file and the gating token — see Write Tools & Spend Controls.

Enabling writes

Writes stay off until all of these are set:

{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": ["-y", "bagos-mcp-server"],
      "env": {
        "BAGS_API_KEY": "your-key-here",
        "BAGS_NETWORK": "mainnet",
        "BAGS_KEYPAIR_PATH": "~/.config/bags/keypair.json",
        "BOS_TOKEN_MINT": "Feqmy64uNvK198MAWFC5ujRnzif6kM9wKonTX2t3BAGS",
        "BAGS_MAX_SOL_PER_TX": "0.1",
        "BAGS_MAX_SOL_PER_SESSION": "1.0"
      }
    }
  }
}

⚠️ BOS_TOKEN_MINT currently does two jobs. It is the token the gate requires you to hold ($BOS, above), and it is the default output mint for a swap that does not name one (ExecuteTrade.ts). Those want opposite properties — a gate wants a token you hold, a swap target wants a token with liquidity, and $BOS has almost none. Always pass outputMint explicitly on bags_execute_trade rather than relying on the default. Splitting these into two variables is tracked as a known issue.

Configuration

🧪 Testing & CI

npm ci
npm run ci            # lint + typecheck + tests with coverage
npm run dev           # stdio server with watch
npm run inspector     # MCP Inspector against the built server
npm run proof:devnet  # land a real devnet transaction through the write path

proof:devnet uses a persisted throwaway keypair (.proof/, gitignored), funds it from the devnet faucet when needed, and pushes a transfer through the same simulate/sign/send/confirm path the write tools use — then re-fetches the signature from the chain instead of trusting the function's return value. That last step is the whole point: a function returning success is a claim, and a signature you can open on an explorer is evidence.

📽️ Demo Materials

• DEMO.md — receipts from a real run against the live Bags mainnet API: 7 scenarios, 8 steps, per-step latency, plus the network-mismatch guard and the token gate caught refusing a write.
• docs/examples.md — prompts you can type at your assistant and what each should do.
• docs/KNOWN_ISSUES.md — what is currently broken and why, including what has already been ruled out. Open advisories are explained there rather than left for you to discover.

🛡️ Security

Read SECURITY.md before pointing a funded wallet at this.

Summary: your private key is read from disk, used to sign, and never logged, never sent anywhere, and never placed in an error message. Tool errors return a message only — no stack traces — with key-shaped strings redacted. The startup report strips credentials from the RPC URL. If the RPC endpoint's cluster disagrees with BAGS_NETWORK, the server refuses to start rather than sign mainnet transactions under a devnet banner.

The same rule now covers the Bags API key: bags_authenticate writes it to ~/.config/bags/credentials.json and echoes only a four-character tail. It used to print the key in full, which published a live credential into the assistant's context and every transcript downstream of it. If you ran bags_authenticate on a version before this change, rotate that key at dev.bags.fm.

Known limits of these controls

Two are worth stating here rather than leaving in SECURITY.md:

• HTTP mode has no authentication. Started with --http, the server listens on 0.0.0.0 with permissive CORS and no auth, so any caller that can reach the port can invoke the write tools — sharing one spend counter. Do not run HTTP mode on a funded wallet. stdio is the default and the only transport this project recommends; it is also why the Smithery listing is stdio-only rather than hosted.
• The session cap counts a trade whose outcome is unknown. If confirmation times out after sending, the spend is counted (it may still land) and the error carries the signature. Restart the server to reset the counter once you have checked it on an explorer.

Report vulnerabilities via GitHub security advisories.

📄 License

MIT — see LICENSE.