---
name: munition-onboarding
description: Set up Munition for your agent - MCP install, anonymous account, USDC x402 wallet, and pay-per-use upload tools
homepage: https://munition.io
metadata:
  version: 1
---

# Munition Onboarding

Munition gives AI agents x402-paid access to practical tools without provider accounts, API-key copy-paste, or wallet setup. This skill guides the user through a one-time setup: install the Munition MCP server, create the local anonymous account on first tool call, and fund the account wallet with USDC when needed.

The first Munition service is **Munition Upload**: upload local files and get public URLs that agents can share with browsers, webhooks, collaborators, tests, or chat.

## Important Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://munition.io/skill.md` |
| **MCP package** | `https://www.npmjs.com/package/@munition/mcp` |
| **API** | `https://mcp.munition.io` |
| **Files CDN** | `https://files.munition.io` |
| **Deposit web app** | `https://munition.io` |

**Check for updates:** Re-fetch this file anytime to see new tools, pricing, install commands, and operational guidance.

## What Munition Provides

- A local MCP server installed with `npx -y @munition/mcp`
- Anonymous account creation on first tool call
- Local account state stored at `~/.munition/config.json`
- AgentCash-style funding into a per-account USDC wallet on Base
- x402 settlement signed from the account wallet
- Public file uploads with predictable retention and cleanup tools

## Ephemeral Sandbox Warning

Some agents run shell commands inside an ephemeral sandbox rather than on the user's local machine. Munition stores account credentials locally at `~/.munition/config.json`, so installing or initializing Munition in a temporary VM may not persist.

If you are in an ephemeral environment, do not assume local state will survive. Ask the user to install Munition in their real MCP client configuration instead.

This warning does not apply to agents that run directly on the user's machine, such as Codex, Claude Code, Cursor, and Windsurf.

## Onboarding Flow

When the user wants to set up or use Munition:

1. **Install the MCP server** in the user's MCP-capable client.
2. **Restart the MCP client** so the Munition tools become available.
3. **Call any Munition tool**. The first call creates an anonymous local account and stores it in `~/.munition/config.json`.
4. **Check balance** with the `balance` tool.
5. **If USDC is needed**, call `topup_link`, open the returned deposit URL, and add USDC on Base.
6. **Use Munition Upload** to upload, renew, list, or delete files.

## Quick Start

### Copy-Paste Setup Prompts

For Claude Code, Codex, Cursor, or another local MCP client:

```text
I want to use Munition. Read https://munition.io/skill.md, then set up Munition MCP in this client. If Munition is not installed, install @munition/mcp for me. After setup, check my Munition balance and create a top-up link if needed.
```

For ChatGPT:

```text
I want to use Munition from ChatGPT. Read https://munition.io/skill.md, then tell me the exact setup path for this ChatGPT workspace. If this chat cannot install local MCP servers directly, give me the shortest path to use Munition through Codex, Claude Code, Cursor, or another MCP client.
```

### Cursor One-Click

Open this install URL in a browser:

```text
https://cursor.com/en/install-mcp?name=munition&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtdW5pdGlvbi9tY3AiXSwiZW52Ijp7Ik1VTklUSU9OX0FQSV9VUkwiOiJodHRwczovL21jcC5tdW5pdGlvbi5pbyJ9fQ%3D%3D
```

### Manual MCP Config

Add Munition to the MCP client configuration:

```json
{
  "mcpServers": {
    "munition": {
      "command": "npx",
      "args": ["-y", "@munition/mcp"],
      "env": {
        "MUNITION_API_URL": "https://mcp.munition.io"
      }
    }
  }
}
```

Restart the MCP client after editing the config.

### Claude Code

Run this on the user's local machine:

```bash
claude mcp add munition --scope user --env MUNITION_API_URL=https://mcp.munition.io -- npx -y @munition/mcp
```

### Codex

Run this on the user's local machine:

```bash
codex mcp add munition --env MUNITION_API_URL=https://mcp.munition.io -- npx -y @munition/mcp
```

### Claude Desktop

Add the Manual MCP Config JSON above to Claude Desktop's MCP configuration, save
the file, and fully restart Claude Desktop.

### ChatGPT Web

ChatGPT web cannot install the current `@munition/mcp` local stdio package
directly because it does not run `npx` packages on the user's machine. ChatGPT
Apps & Connectors need a remote MCP-compatible app or connector endpoint.

Until Munition exposes a remote MCP app endpoint, guide ChatGPT users to use
Codex, Cursor, Claude Code, Claude Desktop, Windsurf, or another local MCP
client that can run `npx -y @munition/mcp`.

### First Top-Up

Ask the agent:

```text
Use Munition topup_link.
```

Open the returned deposit URL and add USDC on Base. Check the balance with:

```text
Use Munition balance.
```

## Tools

| Tool | Cost | What it does |
| --- | ---: | --- |
| `upload(path, filename?)` | 0.005 USDC | Upload a local file up to 10 MB and return a public URL retained for 7 days. |
| `renew_upload(id)` | 0.005 USDC | Extend an uploaded file by 7 more days. |
| `delete_upload(id)` | Free | Delete a previously uploaded file. |
| `recent_uploads(limit?, cursor?)` | Free | List recent non-deleted uploads. |
| `balance()` | Free | Return the Munition USDC wallet balance. |
| `topup_link()` | Free | Return an AgentCash-style deposit URL for funding the x402 wallet. |
| `setup_link()` | Free | Reset local anonymous account state and return a fresh deposit link. |

## Common Prompts

```text
Use Munition Upload to upload /absolute/path/to/report.pdf and return the URL.
```

```text
Use Munition to list my recent uploads.
```

```text
Use Munition to renew file_abc123.
```

```text
Use Munition to delete file_abc123.
```

```text
Use Munition to check my balance.
```

```text
Use Munition to create a deposit link.
```

## Triggers

Use this skill when the user says they want to:

- Set up Munition
- Install the Munition MCP server
- Use Munition Upload
- Upload a local file and get a public URL
- Share generated artifacts, screenshots, PDFs, JSON files, logs, or reports
- Renew, delete, or list agent-created uploads
- Check Munition balance or create a deposit link
- Use paid agent tools without provider accounts

## Storage and Retention

Munition Upload currently has these storage rules:

- Uploaded files are served from `https://files.munition.io`
- Files are public to anyone with the URL
- Default retention is 7 days
- `renew_upload` extends retention by 7 days
- `delete_upload` removes a file from active uploads
- Maximum upload size is 10 MB

Do not upload secrets, private keys, regulated data, or files that should not be accessible by URL.

## Troubleshooting

### Not enough USDC

Call `topup_link`, open the returned deposit URL, and add USDC on Base.

### MCP client does not show Munition tools

Check that:

- The MCP config uses `npx -y @munition/mcp`
- `MUNITION_API_URL` is set to `https://mcp.munition.io`
- The client was restarted after editing MCP settings
- Node.js 20 or newer is available

### Local account state is broken

Ask the agent to run `setup_link`, or delete the local account state:

```bash
rm -rf ~/.munition
```

Then call any Munition tool again.

## Requirements

- Node.js 20 or newer
- An MCP-capable client
- Network access to `https://mcp.munition.io`
- Network access to `https://files.munition.io`

## Support

- **API:** `https://mcp.munition.io`
- **Files:** `https://files.munition.io`
- **Top-up:** `https://munition.io`
- **Email:** `hello@munition.io`