Skip to main content
Glama

npm CI/CD MCP Registry License

🚀 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).

Related MCP server: trade-router-mcp

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

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

npm MCP Registry Smithery GitHub Packages

Live Site Pitch Deck Run Receipts Security Policy Changelog

MCP TypeScript Solana Jest Publish CodeQL Release


💡 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

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.

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:

Signature

2kvu25xW…U5Dm

Cluster

devnet

Slot

484219564

Status

err: null

Captured

2026-08-16

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.

Layer

Status

Details

Real default path

✅

No kill-switch flag in any documented command. USE_MOCK_DATA defaults off; when on, it affects only the bags_get_claimable_fees tool, stamping ⚠️ [MOCK DATA ENABLED] on that tool's own response. The other 13 tools ignore it. Live-run receipts in DEMO.md

Code quality

✅

ESLint + tsc --noEmit, both clean

Unit testing

✅

Jest, 418 tests / 19 suites, 100% statements · branches · functions · lines, enforced

High-signal tests

✅

Mutation-checked cap/confirmation bypass tests · a leak-channel regression test (the API key used to be echoed into tool output) · network-mismatch refusal

Security

✅

CodeQL SAST · Dependabot SCA · gitleaks over full history (fetch-depth: 0) · secret scanning + push protection on · npm audit in CI as a ratchet — see below

Dependency debt

⚠️

6 advisories, 0 critical — down from 90. Everything patchable was cleared with version-scoped overrides (see package.json). The 6 that remain are one root cause, bigint-buffer GHSA-3gc7-fjrx-p6mg, counted once at each level of the chain it travels up to @bagsfm/bags-sdk. No patched bigint-buffer exists — 1.1.5 is the installed version, the latest version, and vulnerable. CI blocks any critical and any increase over .audit-baseline.json. Note: npm honours overrides only in a root project, so these protect this repo and CI, not consumers of the published package.

CI

✅

4 stages (Quality → Security ∥ Test → Build) with cancel-in-progress concurrency; Node 22 + 24 matrix; packaged-artifact and entrypoint checks

CD

✅

Release → tarball audit → npm publish --provenance → deprecate the superseded version. A second workflow submits server.json to the MCP registry via OIDC. Both gated on the full CI suite. 1.0.0 is deprecated on npm with a pointer to the defect it carried.

On-chain proof

✅

npm run proof:devnet lands a real transaction through the production write path and re-fetches it from the chain. Captured 2026-08-16: 2kvu25xW…U5Dm, slot 484219564, err: null. Anyone can re-verify it — see DEMO.md

Community standards

✅

Code of Conduct · Contributing · Security policy · issue + PR templates

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

Variable

Required

Default

Notes

BAGS_API_KEY

yes

—

From dev.bags.fm

BAGS_NETWORK

no

devnet

devnet or mainnet. Writes need mainnet.

SOLANA_RPC_URL

no

public cluster RPC

Must agree with BAGS_NETWORK or the server refuses to start

BAGS_KEYPAIR_PATH

writes only

~/.config/bags/keypair.json

JSON byte-array keypair file

BOS_TOKEN_MINT

writes only

—

Gating token mint

BOS_REQUIRED_BALANCE

no

10000

Minimum gating-token balance. 0 disables the gate (any balance passes); a non-numeric value is refused at startup rather than silently defaulting.

BAGS_MAX_SOL_PER_TX

no

0.1

Per-transaction spend cap

BAGS_MAX_SOL_PER_SESSION

no

1.0

Per-process spend cap

BAGS_ALLOW_UNCONFIRMED

no

false

Skip the confirmation step

BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS

no

false

Permit swaps whose input is not SOL. The caps are SOL-denominated and cannot limit these.

HELIUS_RPC_URL

no

—

Alias for SOLANA_RPC_URL, read only if that is unset

USE_MOCK_DATA

no

false

true makes bags_get_claimable_fees return fabricated balances, stamped as such. No other tool is affected.

BAGS_API_URL

no

https://public-api-v2.bags.fm/api/v1

Override the Bags API base URL used by bags_authenticate. Must be https on bags.fm or a subdomain, because the tool signs what this endpoint sends.

BAGS_ALLOW_CUSTOM_API_URL

no

false

true lifts the bags.fm restriction on BAGS_API_URL. Only for a server you control.

BAGS_ENV_FILE

no

—

Absolute path of an env file to load. A .env in the working directory is never loaded on its own, because an MCP client's working directory is whatever project you have open.

PORT

no

3050

HTTP listener port. Only read when started with --http.


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

Available Tools

14 tools
bags_authenticateA

Authenticate with Bags API utilizing the V2 signature challenge flow. Automatically loads local wallet.

Inputs: privateKeyPath.

bags_claim_feesA

GATED WRITE: Claim pending creator/LP fees for the given token mints. Requires $BOS. Two-step: the first call previews and returns a confirmation token; call again with it to sign and submit. Returns confirmed on-chain signatures.

Inputs: tokenMints (required), confirm.

bags_execute_tradeA

GATED WRITE: Swap tokens on Bags pools. Requires $BOS. Two-step: the first call returns a preview and a confirmation token; call again with that token to sign and submit. Returns a confirmed on-chain signature. SOL mint: So11111111111111111111111111111111111111112.

Inputs: amount, confirm, inputMint, outputMint, +1 more.

bags_get_claimable_feesA

Query all claimable creator/LP fees for a wallet. Free read-only tier.

Inputs: walletAddress.

bags_get_creatorsB

Query top creators by lifetime fees on Bags. Free read-only tier.

Inputs: limit, offset.

bags_get_partner_statsA

View partner referral earnings for the configured wallet. Free read-only tier.

Inputs: partnerId (required).

bags_get_token_analyticsA

Get pool info, claim stats, and bonding curve progress for a token. Free read-only tier.

Inputs: tokenMint (required).

bags_get_token_claim_eventsA

Get the fee-claim audit trail for a token: who claimed, how much, when, and the transaction signature. Paginated via limit/offset. Free read-only tier.

Inputs: tokenMint (required), limit, offset.

bags_get_token_claim_statsA

Get per-creator claim totals for a token: each fee-share creator with their royalty split and total claimed amount. Free read-only tier.

Inputs: tokenMint (required).

bags_get_token_creatorsA

Get the royalty split for a token: every creator sharing its fees, their wallet, social provider, and share in basis points. Free read-only tier.

Inputs: tokenMint (required).

bags_get_trade_quoteA

Get a swap quote to trade SOL and any Bags ecosystem token. Free read-only tier. SOL mint: So11111111111111111111111111111111111111112. Default BOS token mint: EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS.

Inputs: side (required), amount (required), inputMint, outputMint.

bags_heartbeatA

Periodic health check combining basic node status with an earnings/balance summary. Free read-only tier.

Inputs: no named parameters.

bags_prepare_token_metadataA

GATED: Create token info and metadata on Bags, returning the reserved mint address and metadata URL. Requires $BOS. This PREPARES a launch — it does not launch the token and does not send an on-chain transaction.

Inputs: name (required), symbol (required), description (required), imageUrl.

bags_resolve_launch_walletA

Resolve a social handle (twitter, tiktok, kick, or github) to its Bags fee-share launch wallet. Free read-only tier.

Inputs: provider (required), username (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    Each tool targets a distinct operation or resource, and the write vs read-only distinction is clear from descriptions. Minor overlap remains between get_token_analytics and get_token_claim_stats (both expose claim stats) and between get_creators and get_token_creators.

    Naming Consistency4/5

    All tools share the bags_ prefix and mostly follow a verb_object pattern (get_, execute_, claim_, prepare_). Minor deviations include bags_heartbeat, which is a noun, and bags_authenticate, which is a bare verb.

    Tool Count5/5

    14 tools is well within the ideal range and covers authentication, trading, fee claiming, analytics, and token metadata preparation without feeling bloated. Each tool serves a clear purpose in the overall workflow.

    Completeness4/5

    The surface covers the main read-only analytics, trade quoting/execution, fee claims, and metadata preparation workflows. The most notable gap is that a prepared token launch cannot be executed through the server, but the core trade and fee lifecycle is otherwise well covered.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP (Model Context Protocol) server for the MAIN DEX on Base. Provides AI agents (Claude, Cursor, etc.) with tools to interact with the protocol: swap tokens, manage liquidity, enter/exit ALM strategies(10% APY), and more.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Non-custodial Solana swap & limit order engine for AI agents. 21 tools - swap, limit, trailing, TWAP, DCA, combo orders - across Raydium, PumpSwap, Orca, Meteora. Jito MEV-protected execution. Ed25519-verified server messages. Private key never leaves the process.
      21
      183 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server providing Solana/crypto/macro tools (wallet scan, password breach, Jito tip, GitHub health, FRED series, Drift exposure, premium chapters) with x402 payment gating (USDC on Base) for 7 of 8 tools.
      15
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the Monad blockchain. Provides tools for balances, transfers, swaps, and DeFi with Privy wallet signing.
      108 npm
      2
      MIT