Resolves GitHub usernames to fee-share wallet addresses.
Resolves Kick usernames to fee-share wallet addresses.
Enables trading on Solana: fetching token analytics, quotes, claimable fees, executing swaps, and claiming creator fees, with safety controls like confirmation and spend caps.
Resolves TikTok usernames to fee-share wallet addresses.
npx bagos-mcp-serverClaude 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-serverRestart 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: MAIN MCP
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-serverinstalls — 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.
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.
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.
Every write goes through this:
token gate → spend caps → confirmation → simulate → sign → send → confirmTool | Type | What it does |
| read | Server status and wallet reachability |
| read | Lifetime fee data for a token mint |
| read | Top token creators by lifetime fees |
| read | Price quote for a swap. Does not trade. |
| read | Fees currently claimable by your wallet |
| read | Partner config claim statistics |
| read | Per-creator claim totals — the royalty roster with amounts claimed |
| read | The claim audit trail for a token, paginated |
| read | Who shares a token's fees, and in what proportion |
| read | Social handle (twitter/tiktok/kick/github) → fee-share wallet |
| read | Verify wallet ownership via Ed25519 signature |
| gated | Creates token info + metadata. Does not launch a token. |
| write | Swap tokens. Signs and submits. |
| 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.
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.
A real transaction, landed through the production write path and re-fetched from the chain rather than trusted from a return value:
Signature | |
Cluster | devnet |
Slot | 484219564 |
Status |
|
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.
345 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. |
Code quality | ✅ | ESLint + |
Unit testing | ✅ | Jest, 345 tests / 17 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 ( |
Dependency debt | ⚠️ | 6 advisories, 0 critical — down from 90. Everything patchable was cleared with version-scoped |
CI | ✅ | 4 stages (Quality → Security ∥ Test → Build) with |
CD | ✅ | Release → tarball audit → |
On-chain proof | ✅ |
|
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.
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.
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_MINTcurrently 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 passoutputMintexplicitly onbags_execute_traderather than relying on the default. Splitting these into two variables is tracked as a known issue.
Variable | Required | Default | Notes |
| yes | — | From dev.bags.fm |
| no |
|
|
| no | public cluster RPC | Must agree with |
| writes only |
| JSON byte-array keypair file |
| writes only | — | Gating token mint |
| no |
| Minimum gating-token balance. |
| no |
| Per-transaction spend cap |
| no |
| Per-process spend cap |
| no |
| Skip the confirmation step |
| no |
| Permit swaps whose input is not SOL. The caps are SOL-denominated and cannot limit these. |
| no | — | Alias for |
| no |
|
|
| no |
| Override the Bags API base URL used by |
| no |
| HTTP listener port. Only read when started with |
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 pathproof: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.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.
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.
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 is not concurrency-safe. Two writes racing can both pass the check before either records its spend. The per-transaction cap still binds on each.
Report vulnerabilities via GitHub security advisories.
MIT — see LICENSE.
Authenticate with Bags API utilizing the V2 signature challenge flow. Automatically loads local wallet.
| Name | Required | Description | Default |
|---|---|---|---|
| privateKeyPath | No | Optional path to the wallet keypair. Defaults to ~/.config/bags/keypair.json or BAGS_KEYPAIR_PATH env var. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully reveals the V2 signature challenge flow and automatic local-wallet loading, but it does not mention session persistence, whether calling it repeatedly is safe, or what outputs/errors result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the core purpose and key behavioral detail are front-loaded. It is appropriately sized for a tool with one optional parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a single optional parameter, the description is largely sufficient, but it omits usage context (prerequisite for other Bags tools) and there is no output schema to clarify return behavior. Minimal but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single optional parameter's description already covers the default path and environment variable. The tool description adds a relevant behavior note about automatically loading the local wallet, but no additional parameter-level detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Authenticate'), the target resource ('Bags API'), and the mechanism ('V2 signature challenge flow'), which clearly distinguishes it from the other bags_* tools that perform claims, trades, and queries. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when authentication should be performed, whether it is a prerequisite for sibling tools, or when it can be skipped/reused. The implication that authentication is needed before API calls is present but never stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Confirmation token from the preview call. Omit on the first call. | |
| tokenMints | Yes | Token mint addresses to claim fees for (max 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does a solid job: it flags the operation as a gated write, requires $BOS, discloses the two-step confirmation flow, and states the return value (confirmed on-chain signatures). It could add more about failure modes, confirmation-token expiry, or reversibility, but the most decision-relevant behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: 'GATED WRITE' immediately signals the critical nature, followed by purpose, requirement, workflow, and return value. Every sentence contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-step write tool with no output schema and no annotations, the description covers the essential workflow, auth requirement, and result. It is slightly incomplete around failure/edge-case behavior and does not point to the read-only sibling for checking claimable fees first, but an agent can correctly invoke the first and second calls based on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both tokenMints and confirm. The description reinforces the preview/confirm workflow and the 'omit on first call' behavior, but it does not add meaningfully beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Claim'), a precise resource ('pending creator/LP fees'), and the target ('given token mints'). It is clearly distinct from the read-only sibling bags_get_claimable_fees and the trading tool bags_execute_trade, so an agent can understand its purpose without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains the required gating condition ($BOS) and the mandatory two-step workflow: preview first, then confirm. It does not explicitly state when not to use this tool or name alternatives such as bags_get_claimable_fees for checking pending fees first, so it misses the full 'when vs alternatives' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Amount of the input token, human-readable (e.g. 0.1 SOL). Default: 0.1 | |
| confirm | No | Confirmation token from the preview call. Omit on the first call. | |
| inputMint | No | Input token mint. Defaults to SOL: So11111111111111111111111111111111111111112 | |
| outputMint | No | Output token mint. Defaults to BOS: EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS | |
| slippageBps | No | Allowed slippage in basis points. Default 300 (3%). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that this is a gated write, requires $BOS, returns a preview and confirmation token on the first call, and submits an on-chain signature on the second call. This gives agents a solid picture of the tool's side effects and flow, though it does not cover failure modes or what happens if the gate requirements are unmet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the operation type and resource. The SOL mint note is slightly redundant with the schema, but the overall structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations/output schema, the description covers the essential non-obvious aspects: gating, $BOS requirement, two-step confirmation flow, and final on-chain signature. It does not explain error cases or the exact preview payload, but the core invocation knowledge is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minor reinforcing detail about the SOL mint and the confirm token's role, but most parameter meaning is already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'GATED WRITE: Swap tokens on Bags pools', giving a specific verb and resource and explicitly positioning this as the execution counterpart to read/quote tools. It clearly distinguishes itself from siblings like bags_get_trade_quote and claim/read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the two-step invocation flow and the $BOS requirement, which is essential for using the tool correctly. It does not explicitly say 'use this only after a quote' or contrast with alternative tools, but the write-vs-read distinction and two-step protocol make the main usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query all claimable creator/LP fees for a wallet. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| walletAddress | No | Wallet address to check. Defaults to the local keypair wallet if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only, side-effect-free operation, but it omits potential details such as authentication requirements, rate limits, or response format. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no filler. The core operation and the key 'free read-only' constraint are front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only lookup tool with no output schema, this description is nearly complete. It states the purpose, the scope, the wallet parameter, and the cost/side-effect tier. It could mention return shape or authentication posture, but the simple nature of the tool makes those gaps minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional parameter is already well documented with its default behavior. The description adds no additional semantic value beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Query') and a clear resource ('all claimable creator/LP fees for a wallet'), making the tool's purpose immediately obvious. It also distinguishes itself from sibling tools like bags_claim_fees, which perform the actual claiming action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'read-only tier' gives useful context and implies this is the non-mutating counterpart to bags_claim_fees, but it never explicitly names alternatives or states when to choose this tool over another. Usage guidance is implied rather than directly explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query top creators by lifetime fees on Bags. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Amount of creators to return (default 10) | |
| offset | No | Pagination offset (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does state 'Free read-only tier,' which usefully signals safety and lack of mutation. However, it does not mention pagination behavior, response shape, ordering details, or any rate-limit constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the core purpose and then adds the access-tier note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two optional and fully described parameters, so the description is mostly adequate. However, with no output schema, no annotations, and ambiguous siblings, the description could have explained expected return values or distinguished itself from bags_get_token_creators.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter names and descriptions already document limit and offset clearly. The tool description adds no additional meaning beyond the schema, keeping this at the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Query top creators by lifetime fees on Bags.' This differentiates it reasonably from sibling tools like bags_get_token_creators, though it does not explicitly name that alternative. The 'read-only tier' note adds useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to choose this tool over its siblings. It implies a use case—retrieving top creators by fees—but does not mention alternatives, exclusions, or conditions that would route an agent to a different tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View partner referral earnings for the configured wallet. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| partnerId | Yes | The partner's public key address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does state that the tool is read-only and on a free tier, which is useful, but it omits authentication expectations, how the configured wallet is established, and behavior for an invalid or missing partnerId.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the core action front-loaded, plus a short tier qualifier. Every phrase earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool, the description is reasonably complete, but the relationship between 'configured wallet' and the required partnerId is ambiguous. Since there is no output schema, a brief mention of what data is returned would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents partnerId as 'The partner's public key address' with 100% coverage. The description adds no parameter-level meaning and introduces 'configured wallet' without clarifying how it relates to the required partnerId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('View') and a concrete resource ('partner referral earnings'), and scopes it to 'the configured wallet'. This clearly distinguishes the tool from siblings such as bags_get_token_analytics or bags_get_claimable_fees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals when to use the tool: whenever partner referral earnings are needed. It does not explicitly list exclusions or alternatives, but no sibling tool directly overlaps with this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get pool info, claim stats, and bonding curve progress for a token. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| tokenMint | Yes | The token mint address to analyze |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses that the tool is read-only and free, which is useful. But it does not mention authentication requirements (sibling bags_authenticate suggests auth may be needed), rate limits, error behavior, or pagination/return format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the action and scope. Every word earns its place; no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool, the description covers the core subject. However, without an output schema, it would benefit from clarifying the return shape and how it differs from overlapping siblings like bags_get_token_claim_stats and bags_get_partner_stats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single tokenMint parameter with 'The token mint address to analyze,' and the description's 'for a token' adds no new meaning. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Get') and a specific resource set: pool info, claim stats, and bonding curve progress for a token. It is distinct from siblings like bags_get_token_claim_stats by being broader, though it does not explicitly name or contrast siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage through its resource list and the 'Free read-only tier' note, signaling it is a low-cost analytics call. However, it does not explicitly state when to choose this over bags_get_token_claim_stats or other analytics siblings, nor mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return (default 100) | |
| offset | No | Pagination offset (default 0) | |
| tokenMint | Yes | The token mint address to get claim events for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states pagination behavior, the read-only nature, and the free tier, while also listing the returned data fields. It does not mention authentication or rate limits, but for a simple read-only query this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler. It front-loads the core purpose, then adds return fields, pagination, and tier information in an efficient order. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated read-only tool with fully documented schema parameters, the description covers the return content, pagination mechanism, and safety tier. Since no output schema exists, the explicit list of returned fields is especially valuable and sufficient for an agent to understand what this tool provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters with 100% coverage, including defaults for limit and offset and the meaning of tokenMint. The description adds the phrase "Paginated via limit/offset," but this largely restates the schema. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: "Get the fee-claim audit trail for a token" with details on what is returned (who claimed, how much, when, transaction signature). This distinguishes it from siblings like bags_get_token_claim_stats, which would return aggregate statistics rather than individual audit events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is for retrieving paginated audit events and notes it is on the "Free read-only tier," making the safe/read-only use case clear. It does not explicitly name alternatives or state when not to use it, but the audit-trail wording provides sufficient context for selecting it over statistical or claim-execution tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get per-creator claim totals for a token: each fee-share creator with their royalty split and total claimed amount. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| tokenMint | Yes | The token mint address to get claim stats for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose that the operation is free and read-only, which is valuable. However, it does not mention error behavior, empty results, rate limits, or whether the response includes creators with zero claims.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and resource, then adds the return detail and cost/safety signal. Every phrase earns its place, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only query with no output schema, the description provides enough context: what it returns, the grouping scope, and that it is free and read-only. A small gap is that it does not specify behavior for tokens with no claims or invalid mint addresses, but this is minor for a stats endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single parameter 'tokenMint' at 100% coverage. The description adds no additional semantic detail about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get'), a clear resource ('per-creator claim totals for a token'), and specifies the returned fields ('royalty split and total claimed amount'). This clearly distinguishes it from related siblings like bags_get_token_claim_events, which likely returns individual events rather than aggregated totals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need aggregated per-creator claim totals for a specific token. It also notes 'Free read-only tier,' but it does not explicitly state when to choose this over sibling tools such as bags_get_token_claim_events or bags_get_token_creators. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tokenMint | Yes | The token mint address to look up creators for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries disclosure burden, and it does state the call is read-only and free, addressing side effects and cost. It also hints at response semantics by listing the fields returned. It stops short of disclosing auth requirements, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence states the core operation, then the details, and closes with the access tier. No filler or redundant restating of parameter names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema getter, the description covers the operation, the return data, and the access/safety profile. It is slightly incomplete around authentication prerequisites and sibling differentiation, but the low complexity keeps these gaps minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single tokenMint parameter is already described as 'The token mint address to look up creators for'. The description only refers to 'a token' generically and adds no mint-format or usage detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb ('Get'), a concrete resource ('royalty split for a token'), and enumerates the returned data (creators, wallet, social provider, share in basis points). The fee-sharing focus helps distinguish it from the sibling bags_get_creators even without an explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Apart from labeling the call 'free read-only tier', the description offers no guidance about when to prefer this tool over the sibling creator/analytics tools. There is no when/when-not statement or explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a swap quote to trade SOL and any Bags ecosystem token. Free read-only tier. SOL mint: So11111111111111111111111111111111111111112. Default BOS token mint: EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS.
| Name | Required | Description | Default |
|---|---|---|---|
| side | Yes | Is this a buy or sell action? | |
| amount | Yes | Amount of input token to swap in human-readable units (e.g., 0.1 for 0.1 SOL). | |
| inputMint | No | Input token mint address. Defaults to SOL: So11111111111111111111111111111111111111112 | |
| outputMint | No | Output token mint address. Defaults to BOS: EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states 'Free read-only tier,' indicating no cost and no side effects, which is the most important behavioral trait for a quote tool. It does not cover every nuance like quote expiry or liquidity reservation, but the key read-only behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by the free read-only note and the mint details. The only minor redundancy is repeating default mint addresses also present in the schema, but the overall structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple quote tool with fully covered parameters and no output schema, the description provides enough context for an agent to know what to invoke and why. The main gap is that authentication requirements are not explicitly addressed, despite a sibling bags_authenticate tool, though 'free read-only tier' hints at low-friction access.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats the default SOL and BOS mint addresses already present in the schema, adding no substantial new parameter semantics beyond what is already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), a clear resource ('a swap quote'), and a precise scope ('trade SOL and any Bags ecosystem token'). It naturally distinguishes itself from the sibling bags_execute_trade by focusing on quotes instead of execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Get a swap quote' and the explicit 'Free read-only tier' establish clear context for when this tool is appropriate: for obtaining quotes without executing trades. It does not explicitly name alternatives or say 'use this before executing,' but the intended context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Periodic health check combining basic node status with an earnings/balance summary. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that the tool is read-only and free, which helps an agent understand safety and cost. It does not mention authentication needs, rate limits, or the exact meaning of 'node status', but the read-only/free characterization is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. The core purpose is front-loaded, and the 'Free read-only tier' clause adds valuable safety/cost context without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool, the description covers the essential purpose and names the key output components: node status and earnings/balance summary. There is no output schema, so exact field details are absent, but the description is likely sufficient for an agent to select and call this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. The description adds no parameter information, and none is needed because the schema shows an empty object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a periodic health check that combines node status with an earnings/balance summary. It is distinct from sibling tools, none of which are a heartbeat. However, it lacks a direct verb like 'returns' or 'reports', making the action slightly implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies periodic usage but gives no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites such as authentication, nor does it contrast with sibling tools like bags_get_partner_stats or bags_get_token_analytics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The full name of the new token | |
| symbol | Yes | The ticker symbol | |
| imageUrl | No | URL of the token image | |
| description | Yes | Description for the token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that this is a preparation step, does not launch the token, and does not send an on-chain transaction. It also discloses the $BOS requirement and the outputs. It could add what happens if $BOS is absent, but the current disclosure is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the gating requirement, then states the purpose, outputs, and key non-behaviors. Every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for an agent to understand what this tool does, what it returns, and that it has no on-chain side effects. The output is described, and the input schema covers the parameters. A complete picture is present, though it could mention prerequisites for obtaining or using $BOS or the fate of the reserved mint address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all four parameters. The description broadly refers to 'token info and metadata' but adds no per-parameter meaning beyond the schema. This meets the baseline for high schema coverage but does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create token info and metadata on Bags,' and explicitly identifies the return values (reserved mint address and metadata URL). It also distinguishes the tool from a token launch by clarifying that it only prepares a launch, which separates it from related launch-flow tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: before launching a token, to prepare metadata. It also gives an explicit exclusion: it does not launch the token and sends no on-chain transaction. However, it does not name an alternative sibling tool or provide a direct comparison, so the routing guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a social handle (twitter, tiktok, kick, or github) to its Bags fee-share launch wallet. Free read-only tier.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | The social platform the username belongs to | |
| username | Yes | The username to resolve (a leading @ is stripped automatically) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description correctly carries the safety burden by explicitly labeling the operation as 'read-only' and 'free.' It does not describe failure behavior or rate limits, but for a simple resolver this is adequate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the action and resource, lists providers economically in parentheses, and appends the cost/read-only hint. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with fully documented schema and no output schema, the description provides enough context to understand the input domain and the expected result. The main omissions are exact return payload and any authentication caveats, but these are minor for this simple lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the input schema with 100% coverage. The description lists the supported providers, but this largely duplicates the enum rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resolve') and a clear resource ('a social handle ... to its Bags fee-share launch wallet'), and enumerates the supported platforms. This distinguishes it clearly from sibling tools that execute trades, claim fees, or fetch analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: when you have a social handle and need the corresponding fee-share launch wallet. It does not explicitly name an alternative or exclusion, but no sibling tool appears to perform this resolution, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.6.0bags_authenticatebags_claim_feesbags_execute_tradebags_get_claimable_feesbags_get_creatorsbags_get_partner_statsbags_get_token_analyticsbags_get_token_claim_eventsbags_get_token_claim_statsbags_get_token_creatorsbags_get_trade_quotebags_heartbeatbags_prepare_token_metadatabags_resolve_launch_walletEach 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.
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.
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.
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.
Solana MCP for wallets, trades, markets, PnL, transfers, onchain data, signable swaps and API tools.
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Solana on-chain intelligence — token scans, wallet profiling, bundle detection, 19 MCP tools.
Solana MCP developer toolkit: wallets, trades, markets, PnL, transfers, onchain, swaps & API tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/edycutjong/BagOS'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
