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: "check the bagos heartbeat". The server prints a configuration report to stderr on startup; if something is missing it tells you which variable and why. A key alone gives you the 11 read tools — 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

💡 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

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.

📊 Engineering Rigor

337 tests. The bypass tests around the spend caps and the confirmation step are load-bearing; treat a change there as a security change. They are mutation- checked: removing the cap guard, the confirmation check, the decimals lookup, or the spend recorder each makes the suite fail.

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 equivalent end-to-end coverage is npm run demo, which drives all read tools over real MCP JSON-RPC against the live API.

🚀 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": "EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS",
        "BAGS_MAX_SOL_PER_TX": "0.1",
        "BAGS_MAX_SOL_PER_SESSION": "1.0"
      }
    }
  }
}

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.

Report vulnerabilities via GitHub security advisories.

📄 License

MIT — see LICENSE.