edycutjong/BagOS

An MCP server that lets an AI assistant trade on Solana — and signs nothing until you say so.
## 🚀 Install
bash
npx bagos-mcp-server
Claude Desktop — ~/Library/Application Support/Claude/claudedesktopconfig.json
(macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows):
json
"mcpServers": {
"bagos": {
"command": "npx",
"args": ["-y", "bagos-mcp-server"],
"env": {
"BAGSAPIKEY": "your-key-here"
Claude Code:
bash
claude mcp add bagos --env BAGSAPIKEY=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 — bagsheartbeat,
bagsgetclaimablefees and bagsauthenticate — report on your wallet, so they also
need BAGSKEYPAIRPATH 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.
⚠️ 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: