@munition/mcp

@munition/mcp

Munition is a pay-per-use service layer for AI agents. Today it ships two MCP services: Upload (file -> public URL) and Flight Search (Duffel-backed live offers). More services are coming.

Status: v0.0.12 alpha

Services

Service	Cost	Use it when your agent needs to...
Upload	0.005 USDC per upload or renew	Turn a local file into a public URL, keep it for 7 days, renew it, delete it, or list recent uploads.
Flight Search	0.05 USDC per search	Find live flight offers with prices, airlines, itineraries, and segments.
Account	Free	Check wallet balance, create a deposit link, or reset local account state.

Munition creates an anonymous local account on the first tool call. Paid calls settle in USDC on Base through the account's x402 wallet.

Install

Munition runs as a local stdio MCP server. Requirements: Node.js 20+, network access to https://api.munition.io, and an MCP client that can run local commands.

Cursor

Claude Code / Codex

claude mcp add munition --scope user --env MUNITION_API_URL=https://api.munition.io -- npx -y @munition/mcp
# or:
codex mcp add munition --env MUNITION_API_URL=https://api.munition.io -- npx -y @munition/mcp

Manual MCP config

Use this same server definition in Cursor, Claude Desktop, Windsurf, Gemini CLI, or any local stdio MCP client:

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

Restart the MCP client after changing config.

More clients

Claude Desktop uses the manual JSON above. ChatGPT Web and Claude Web custom connectors require a remote MCP endpoint; this npm package is local stdio, so use Cursor, Claude Code, Codex, Claude Desktop, or another local MCP client for now.

Tools

Tool	Cost	What it returns
upload(path, filename?, tags?)	0.005 USDC	Public URL plus file metadata.
search_flights(origin, destination, departureDate, ...)	0.05 USDC	Live flight offers with prices and itineraries.
renew_upload(id)	0.005 USDC	New expiration and renewal metadata.
delete_upload(id)	Free	{ "ok": true } after deleting an active upload.
recent_uploads(limit?, cursor?)	Free	Recent non-deleted upload records and pagination cursor.
balance()	Free	Account wallet address and USDC balance.
topup_link()	Free	Deposit URL for funding the x402 wallet.
setup_link()	Free	Fresh anonymous account and deposit link.

Tool details

upload(path, filename?, tags?)

Uploads a local file up to 10 MB and returns a public URL retained for 7 days.

Input:

{
  "path": "/absolute/path/to/report.pdf",
  "filename": "optional-url-name.pdf",
  "tags": ["agent-output", "report"]
}

Rules:

• path must be absolute and point to a regular file.
• filename is optional URL naming metadata.
• tags is optional: up to 20 non-empty strings, max 64 characters each.
• Do not upload secrets, private keys, regulated data, or files that should not be public by URL.

Output includes id, url, size, mime, hash, and tags.

search_flights(...)

Searches live Duffel-backed flight offers. Costs 0.05 USDC.

Input:

{
  "origin": "SFO",
  "destination": "NRT",
  "departureDate": "2026-07-14",
  "returnDate": "2026-07-28",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "travelClass": "ECONOMY",
  "nonStop": false,
  "currency": "USD",
  "maxPrice": 1500,
  "maxResults": 10
}

Fields:

• origin, destination: required 3-letter IATA airport codes.
• departureDate: required YYYY-MM-DD date.
• returnDate: optional YYYY-MM-DD date for round trips.
• adults, children, infants: passenger counts; defaults are 1, 0, and 0.
• travelClass: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST; default ECONOMY.
• nonStop: optional direct-flight filter.
• currency: optional 3-letter code used with maxPrice (currencyCode in direct HTTP examples).
• maxPrice: optional max total offer price; no currency conversion is applied.
• maxResults: optional result cap, 1-50; default 50.

Expected output: a flight offers array (results) with itineraries and segments, plus search metadata.

Output:

{
  "results": [
    {
      "id": "off_123",
      "source": "flight_search",
      "totalPrice": "512.30",
      "currency": "USD",
      "airlineCodes": ["AF"],
      "itineraries": [
        {
          "duration": "PT11H25M",
          "numberOfStops": 0,
          "segments": [
            {
              "departure": { "airportCode": "SFO", "at": "2026-07-14T10:00:00" },
              "arrival": { "airportCode": "NRT", "at": "2026-07-15T13:25:00" },
              "carrierCode": "AF",
              "flightNumber": "123",
              "duration": "PT11H25M"
            }
          ]
        }
      ]
    }
  ],
  "meta": { "resultCount": 1, "searchedAt": "2026-05-19T12:00:00Z" }
}

recent_uploads(limit?, cursor?)

Lists recent non-deleted uploads for the local account.

Input:

{ "limit": 20, "cursor": 0 }

Output includes items with id, url, size, mime, hash, originalFilename, tags, uploadedAt, expiresAt, renewalCount, and txHash, plus nextCursor or null.

renew_upload(id)

Extends an uploaded file by 7 more days.

{ "id": "file_abc123" }

Returns the file id, new expiresAt, renewalCount, and settlement metadata.

delete_upload(id)

Deletes a previously uploaded file from active uploads.

{ "id": "file_abc123" }

Returns { "ok": true }.

balance()

Returns the current Munition account wallet balance:

{
  "accountId": "acct_123",
  "currency": "USDC",
  "network": "base",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "balanceUsdcAtomic": "1250000",
  "balanceUsdc": "1.25"
}

topup_link()

Returns a deposit URL like https://munition.io/deposit/<wallet>?network=base. Open it, fund the wallet with USDC on Base, then retry paid calls.

setup_link()

Clears local anonymous account credentials, creates a fresh account, and returns a deposit link. Use it if local state is broken or you want to start over.

Pricing

Action	Price
Upload file	0.005 USDC
Renew upload for 7 days	0.005 USDC
Search flights	0.05 USDC
Delete upload	Free
List recent uploads	Free
Check balance	Free
Generate deposit/setup link	Free

If a paid call fails for insufficient funds, call topup_link(), open the deposit URL, and add USDC on Base.

Configuration and local state

Environment variables:

Variable	Default	Description
MUNITION_API_URL	https://api.munition.io	Munition API origin. Use http://localhost:4022 for local server development.
MUNITION_CONFIG	~/.munition/config.json	Local account config path.

Munition stores anonymous account credentials at ~/.munition/config.json: API base URL, account id, and account token. To reset it manually:

rm -rf ~/.munition

Or ask your agent to call setup_link().

How it works

• Your MCP client starts npx -y @munition/mcp over stdio.
• The first tool call creates or loads an anonymous local account.
• Free tools call the Munition API directly.
• Paid tools use the account wallet to settle x402 in USDC on Base.
• Upload uses a presigned file transfer plus paid finalize step; Flight Search calls Duffel and returns normalized offers.
• The MCP tool returns structured JSON to the agent.

Common prompts

Use Munition to upload /Users/me/Desktop/result.json and return the public URL.

Use Munition search_flights for SFO to NRT departing 2026-07-14, returning 2026-07-28, 1 adult, economy, max 5 results under 1500 USD.

Use Munition to list my recent uploads.

Use Munition to renew file_abc123, then check my balance.

Use Munition to create a deposit link so I can fund the wallet.

Troubleshooting

account token missing

Run setup_link() or delete local state with rm -rf ~/.munition, then call any Munition tool again.

Not enough USDC

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

file too large

The upload limit is 10 MB. Compress the file or upload a smaller artifact.

upload path must be absolute

Use an absolute path, for example /Users/me/Desktop/report.pdf.

MCP client does not show Munition tools

Check that the config uses npx -y @munition/mcp, MUNITION_API_URL=https://api.munition.io, Node.js 20+, and that the client was restarted after config changes.

Links

• API: https://api.munition.io
• Files: https://files.munition.io
• Deposit web app: https://munition.io
• Repository: https://github.com/benjammartin/munitionx402