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

# Munition Onboarding

Munition is agentic x402 infrastructure for small paid services. It gives AI agents access to paid capabilities without provider accounts, API-key copy-paste, or wallet setup. This skill guides the user through one-time setup for the local MCP adapter: install the Munition MCP server, create the local anonymous account on first tool call, and fund the account wallet with USDC when needed.

Munition direct paid routes accept USDC on Base, Polygon, Arbitrum (all via x402 + MPP) and Solana (x402 only). The per-account topup wallet is Base-only.

Current Munition services include **Munition Upload** for temporary public file URLs, **Munition Flight Search** for live flight offer search, **Munition Airport Search** for airport reference data, and **Munition Flight Offer Details** for paid offer lookups.

## Important Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://munition.io/skill.md` |
| **Upload service page** | `https://munition.io/upload` |
| **MCP package** | `https://www.npmjs.com/package/@munition/mcp` |
| **MCP package metadata** | `https://api.munition.io/.well-known/mcp-server.json` |
| **Munition API origin** | `https://api.munition.io` |
| **Direct Upload API** | `https://api.munition.io/v1/uploads` |
| **Direct Flight Search API** | `https://api.munition.io/v1/flights/search` |
| **Direct Airport Search API** | `https://api.munition.io/v1/airports/search` |
| **Direct Flight Offer Details API** | `https://api.munition.io/v1/flights/offers/{id}` |
| **Files CDN** | `https://files.munition.io` |
| **Top-up 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 stdio MCP server installed with `npx -y @munition/mcp`
- A wrapper for multiple paid agent services
- A direct x402 HTTP API for services that can be bought without installing MCP
- A current service catalog, including Munition Upload, Munition Flight Search, Munition Airport Search, and Munition Flight Offer Details
- Anonymous account creation on first Munition tool call
- Local account state stored at `~/.munition/config.json`
- deposit funding into a per-account USDC wallet on Base
- x402 settlement signed from the account wallet
- Service-specific tools exposed through the same account, wallet, and payment flow

## Current Services

### Munition Upload

Use Munition Upload when the user needs an agent to publish a local artifact and return a public URL. Good fits include generated PDFs, screenshots, images, rendered reports, JSON files, logs, and temporary files that need to be shared with browsers, webhooks, collaborators, tests, or chat.

Munition Upload is not the whole Munition product. It is one paid service exposed through the Munition wrapper.

Direct x402/Bazaar clients can buy an upload slot at `POST https://api.munition.io/v1/uploads`. Cost: `0.005 USDC` via x402 on Base, Polygon, Arbitrum, or Solana, or via MPP on Base, Polygon, or Arbitrum. Local MCP clients should still use `@munition/mcp` because it can read local file paths before uploading.

Uploads can include optional `tags` metadata. The `tags` field is always a JSON array of strings such as `["agent-output", "report"]`; it is supported by direct upload slot creation and by the MCP `upload` tool. Tags are returned on upload responses and recent upload history so agents can categorize generated artifacts. `tags` may be omitted for backward compatibility, or set to `[]` when no labels are needed. If provided, use at most 20 non-empty string tags, each 64 characters or shorter.

### Munition Flight Search

Use Munition Flight Search when an AI agent needs to search live flight offers for itinerary planning, price comparison, travel research, or downstream booking handoff. The MCP tool name is `search_flights`, and direct x402/Bazaar clients can call `POST https://api.munition.io/v1/flights/search`.

Cost: `0.05 USDC` via x402 on Base, Polygon, Arbitrum, or Solana, or via MPP on Base, Polygon, or Arbitrum per search.

Input shape:

```json
{
  "origin": "SFO",
  "destination": "NRT",
  "departureDate": "2026-08-10",
  "returnDate": "2026-08-21",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "travelClass": "ECONOMY",
  "nonStop": false,
  "maxResults": 10,
  "maxPrice": 900,
  "currency": "USD"
}
```

Required fields are `origin`, `destination`, and `departureDate`. `origin` and `destination` are 3-letter IATA airport codes; dates use `YYYY-MM-DD`. The result contains normalized offers with prices, currency, airline codes, itineraries, and search metadata.

### Munition Airport Search

Use Munition Airport Search when an AI agent needs normalized airport records before travel planning. Direct x402/Bazaar clients can call `POST https://api.munition.io/v1/airports/search`.

Cost: `0.001 USDC` via x402 on Base, Polygon, Arbitrum, or Solana per search. MPP is not advertised for this route.

### Munition Flight Offer Details

Use Munition Flight Offer Details when an AI agent already has a Duffel flight offer id and needs baggage, cabin, fare conditions, itinerary segments, and total price details before booking or handoff. Direct x402/Bazaar clients can call `GET https://api.munition.io/v1/flights/offers/{id}`.

Cost: `0.01 USDC` via x402 on Base, Polygon, Arbitrum, or Solana per lookup. MPP is not advertised for this route.

### Munition Upload Renew/Delete Direct Routes

Direct clients can renew upload links at `POST https://api.munition.io/v1/uploads/{id}/renew` for `0.005 USDC` via x402 on Base, Polygon, Arbitrum, or Solana, or via MPP on Base, Polygon, or Arbitrum. Direct clients can delete uploads at `DELETE https://api.munition.io/v1/uploads/{id}` for `0.001 USDC` on the same direct route networks.

## Pick the Right Install Path

### Local MCP clients

Use the `npx -y @munition/mcp` install path when the user's agent client can run a local stdio MCP server. This includes Codex, Cursor, Claude Code, Claude Desktop, Windsurf, Gemini CLI, and similar local MCP-capable tools.

Local clients are the primary Munition path today because Munition Upload reads local files before uploading them.

### ChatGPT Web, Claude Web, and remote connector clients

ChatGPT Web and Claude Web do not run `npx` packages on the user's machine. They can use Munition only through a public remote MCP server that speaks ChatGPT/Claude's supported remote MCP transport.

The current public npm package, `@munition/mcp`, is a local stdio server. Do not tell the user to paste `npx -y @munition/mcp` into ChatGPT Web or Claude Web.

If Munition publishes a remote MCP endpoint, add it through:

- ChatGPT: Settings -> Apps or Connectors -> Advanced settings -> Developer mode -> create/add the Munition remote MCP app.
- Claude: Customize -> Connectors -> + -> Add custom connector -> add the Munition remote MCP URL.

Do not use `https://api.munition.io` as a ChatGPT or Claude remote MCP URL unless Munition documentation explicitly says that endpoint now supports remote MCP. In this document, `https://api.munition.io` is the HTTP API origin used by the local MCP package.

## 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 run `npx -y @munition/mcp` just to "install Munition" inside the sandbox. Instead, give the user the appropriate local client command or MCP JSON config below and ask them to add it to their real MCP client.

This warning does not apply when the agent is running directly in the user's intended MCP client and can persist MCP configuration and `~/.munition/config.json`.

## Onboarding Flow

When the user wants to set up or use Munition:

1. **Check the environment.** If the client can run local stdio MCP servers, use the local install path. If it is ChatGPT Web or Claude Web, use a remote MCP connector only when Munition has published one.
2. **Install the MCP server** in the user's MCP-capable client.
3. **Restart or refresh the MCP client** so the Munition tools become available.
4. **Call `balance`.** The first Munition tool call creates an anonymous local account and stores it in `~/.munition/config.json`.
5. **If USDC is needed**, call `topup_link`, open the returned deposit URL, and add USDC on Base.
6. **Use a Munition service.** Today that means Munition Upload for files, Munition Flight Search for live flight offers, Airport Search for airport reference data, or Flight Offer Details for paid offer lookups.

## Quick Start Prompt

Paste this into an AI coding tool that can read URLs and configure MCP:

```text
Set up https://munition.io/skill.md
```

If the agent can make persistent local changes, it should install Munition with the commands below. If not, it should show the user the exact command or JSON config to add manually.

## Local Install Commands

### Cursor One-Click

Open this install URL in a browser:

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

### Claude Code

Run this on the user's local machine:

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

Then restart Claude Code or run `/mcp` to verify the server is available.

### Codex

Run this on the user's local machine:

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

### Claude Desktop

Add this JSON block to Claude Desktop's MCP configuration, save the file, and fully restart Claude Desktop:

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

### Manual MCP Config

For any local MCP client that supports stdio servers, add:

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

Restart the MCP client after editing the config.

### ChatGPT Web

ChatGPT Web supports remote MCP apps/connectors in Developer mode. It does not run local stdio MCP packages such as `@munition/mcp`.

Use this only when Munition has a documented remote MCP endpoint:

```text
Settings -> Apps or Connectors -> Advanced settings -> Developer mode
Create or add a Munition remote MCP app
Server URL: <Munition remote MCP URL>
```

If the user only has the local npm package today, direct them to Codex, Cursor, Claude Code, Claude Desktop, or another local MCP client.

### Claude Web / Claude Custom Connectors

Claude custom connectors use remote MCP. They do not install the local npm package on the user's machine.

Use this only when Munition has a documented remote MCP endpoint:

```text
Customize -> Connectors -> + -> Add custom connector
Name: Munition
URL: <Munition remote MCP URL>
```

If the user wants local-file upload from their machine, use Claude Code or Claude Desktop with the local MCP config above.

## 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.
```

## Current Service Tools

| Tool | Cost | What it does |
| --- | ---: | --- |
| `upload(path, filename?, tags?)` | 0.005 USDC | Upload a local file up to 10 MB and return a public URL plus tags metadata, retained for 7 days. |
| `search_flights(origin, destination, departureDate, returnDate?, adults?, children?, infants?, travelClass?, nonStop?, maxResults?, maxPrice?, currency?)` | 0.05 USDC | Search live flight offers and return normalized itineraries, prices, carriers, and metadata. |
| `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 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 Upload to upload /absolute/path/to/report.pdf with tags ["agent-output", "report"] and return the URL.
```

MCP tool input shape for tagged uploads:

```json
{
  "path": "/absolute/path/to/report.pdf",
  "filename": "report.pdf",
  "tags": ["agent-output", "report"]
}
```

```text
Use Munition Flight Search to search flights from SFO to NRT departing 2026-08-10 for 1 adult.
```

MCP tool input shape for flight search:

```json
{
  "origin": "SFO",
  "destination": "NRT",
  "departureDate": "2026-08-10",
  "adults": 1,
  "maxResults": 10
}
```

```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
- Use Munition as an agentic wrapper for paid services
- Install the Munition MCP server
- Discover available Munition services
- Use Munition Upload
- Use Munition Flight Search or the `search_flights` tool
- 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://api.munition.io`
- The client was restarted after editing MCP settings
- Node.js 20 or newer is available

### ChatGPT or Claude Web cannot add Munition

ChatGPT Web and Claude Web need a remote MCP endpoint. The local npm package is for clients that can run stdio MCP servers. Use a local MCP client today, or add Munition's remote MCP URL when Munition publishes one.

### 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
- A local MCP-capable client for the current npm package
- Network access to `https://api.munition.io`
- Network access to `https://files.munition.io`

## Support

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