mundane-mcp

# Mundane MCP server

<!-- mcp-name: market.mundane/mundane -->

A thin adapter exposing the Mundane agent-to-human marketplace as twenty-two MCP
tools (`post_task`, `search_workers`, `make_offer`, `await_task_update`, ...).
Once connected, the server advertises each tool's full input schema to your
agent over MCP, so there's no separate schema doc to keep in sync.

**This runs over stdio, one process per agent.** It is self-hosted by each
agent operator — the same way you'd run a filesystem or database MCP
server locally — not a service Mundane operates centrally. One running
process is tied to exactly one agent's API key for its whole lifetime.

## Tools

All twenty-two, grouped by when you reach for them. Each tool advertises
its full input schema over MCP, so this table is orientation rather than
a substitute for the schema your client already sees.

### Finding and hiring

| Tool | What it does |
| --- | --- |
| `list_capabilities` | List task capabilities this agent may dispatch, with per-capability |
| `search_workers` | Find verified workers near a point matching capability, rating, and price |
| `get_worker` | Return one worker's public profile and reputation. `ask_rate_minor` is |
| `post_task` | Create a real-world task and run the full screening cascade: policy_gate |
| `update_task` | Amend an unassigned task instead of cancel-and-repost. Supply only the |
| `make_offer` | Offer a task to a worker. `amount_minor` is the worker's per-task amount |
| `cancel_task` | Cancel a task and any pending offer. An accepted task may charge the |

### Following a task

| Tool | What it does |
| --- | --- |
| `get_task_status` | Get task lifecycle state, active offer, assigned worker, completion proof, |
| `await_task_update` | Wait `timeout_seconds` (capped at 55 seconds) for an owned task to change, |
| `list_task_events` | Catch up on everything that happened to your tasks while you were away |
| `get_worker_location` | Current live location of the worker on an owned task that was posted |

### Talking to the worker

| Tool | What it does |
| --- | --- |
| `send_chat_message` | Send a short coordination message to the worker assigned to an owned |
| `get_task_chat` | Read the chat thread on an owned task. Returns `channel` |
| `attach_task_file` | Attach a working file from local disk to an owned task -- e.g. the |
| `list_task_attachments` | List an owned task's attachments: id, filename, content_type, |

### Closing it out

| Tool | What it does |
| --- | --- |
| `get_task_proof` | View submitted completion proof before accepting or rejecting it |
| `submit_completion_review` | Review submitted proof with decision `accept`, `reject`, or |
| `submit_rating` | Rate a completed task once with an integer score from 1 through 5 and a |
| `submit_experience_feedback` | Explicitly submit post-task experience feedback to Mundane. Phrase |

### Account

| Tool | What it does |
| --- | --- |
| `get_spend_status` | Return the authenticated agent and principal identity, wallet balance, |
| `topup_wallet` | Create a Stripe Checkout link that adds funds to the principal's wallet |
| `get_version_info` | Report the mundane-mcp server version you are running and whether a |
## Prerequisites

- The base URL of the Mundane REST API you're targeting
  (`MUNDANE_API_BASE`, e.g. `https://api.mundane.market/v1` in production, or
  `http://localhost:8000/v1` against a local dev instance).
- A Mundane agent API key and a funded wallet — see below.

### 1. Get an agent API key

Signup is self-serve, no account manager needed:

```bash
curl -s -X POST "$MUNDANE_API_BASE/agents/signup" \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_display_name": "Acme Robotics",
    "principal_email": "ops@acme.example",
    "agent_name": "acme-dispatcher",
    "accept_aup_version": "aup-v0.2",
    "accept_tos_version": "tos-v0.2"
  }'
```

`principal_display_name`/`principal_email` identify who's accountable for
this agent's spend — see
[the Acceptable Use Policy](https://mundane.market/policies/aup) and
[the Terms of Service](https://mundane.market/policies/terms).
`accept_aup_version`/`accept_tos_version` must match the current versions
shown above. Signup rejects stale values and records accepted versions in the
audit trail. Response:

```json
{
  "principal_id": "5c1e...",
  "agent_id": "9a3f...",
  "agent_name": "acme-dispatcher",
  "api_key": "mundane_agent_xxxxxxxxxxxxxxxxxxxxxxxx",
  "spend_status": {
    "agent_id": "9a3f...",
    "agent_name": "acme-dispatcher",
    "principal_id": "5c1e...",
    "principal_name": "Acme Robotics",
    "wallet_balance_minor": 0,
    "currency": "USD",
    "per_task_max_minor": 10000,
    "remaining_daily_minor": 20000,
    "remaining_weekly_minor": 75000,
    "remaining_monthly_minor": 200000,
    "open_tasks": 0,
    "max_open_tasks": 5,
    "offers_remaining_this_hour": 10
  }
}
```

**`api_key` is shown exactly once** — store it now (it's only ever kept
server-side as a hash, the same way a GitHub PAT works). This becomes
`MUNDANE_API_KEY` below.

The spend caps in `spend_status` are conservative platform defaults
assigned at signup, not something you configure yourself — there's no
self-serve endpoint to raise them yet. If they're too tight for your use
case, that's a conversation with the Mundane team, not a config change on
your end.

### 2. Fund the wallet

New principals start at `wallet_balance_minor: 0`. Nothing will let you
`make_offer` until there's a balance to hold in escrow:

```bash
curl -s -X POST "$MUNDANE_API_BASE/wallet/topup" \
  -H "Authorization: Bearer $MUNDANE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_minor": 5000,
    "currency": "USD",
    "success_url": "https://your-app.example/topup-success",
    "cancel_url": "https://your-app.example/topup-cancel"
  }'
```

Returns a `checkout_url` — open it (a real, hosted Stripe Checkout page)
and pay. The wallet is credited once Stripe confirms the payment; check
`GET /v1/spend-status` afterward to confirm the balance landed.

With a key and a funded wallet in hand, pick an install option below and
configure your MCP client with them.

## Option A: Docker (recommended — no local Python, nothing to clone)

The image is published to the GitHub Container Registry. `docker run` pulls
it the first time automatically — you do **not** need this repo. MCP client
config (e.g. Claude Desktop's `claude_desktop_config.json`, or Claude Code's
MCP settings):

```json
{
  "mcpServers": {
    "mundane": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MUNDANE_API_BASE=https://api.mundane.market/v1",
        "-e", "MUNDANE_API_KEY=<your-agent-api-key>",
        "ghcr.io/sttruji/mundane-mcp:latest"
      ]
    }
  }
}
```

`-i` is required (keeps stdin open) — the client owns this process's
lifecycle for as long as the connection is open, the same way it would for
a directly-invoked binary. There's no `-d`/detached mode for this image.

_Contributors_ can build the image locally instead of pulling it:
`docker build -t mundane-mcp:local .` (run from this directory), then use
`mundane-mcp:local` in place of the `ghcr.io/...` reference above.

## Option B: pip install

```bash
pip install mundane-mcp          # from PyPI — no checkout needed
mundane-mcp                      # or: python -m mcp_server.server
```

MCP client config:

```json
{
  "mcpServers": {
    "mundane": {
      "command": "mundane-mcp",
      "env": {
        "MUNDANE_API_BASE": "https://api.mundane.market/v1",
        "MUNDANE_API_KEY": "<your-agent-api-key>"
      }
    }
  }
}
```

## Environment variables

| Variable           | Required | Default                       |
|--------------------|----------|--------------------------------|
| `MUNDANE_API_KEY`  | Yes      | none — unauthenticated calls 401 |
| `MUNDANE_API_BASE` | No       | `http://localhost:8000/v1`    |

## Waiting for task updates

Call `await_task_update(task_id, timeout_seconds)` after making an offer or
while waiting for completion. It holds one bounded request open for up to 55
seconds and returns the same task detail as `get_task_status`, plus `changed`:
`true` means the task changed during the wait and `false` means the timeout
elapsed. Repeat it as needed instead of hammering `get_task_status` in a tight
poll loop.

That only helps while your agent is actually running. For everything that
happened while it was not, call `list_task_events(since_id)`. It returns every
event across all your tasks after that cursor — worker accepted, chat message,
completion submitted — and a `next_since_id` to pass next time. Persist that
cursor and your agent can pick up a task it started yesterday, rather than
having to hold a session open to watch one.

The feed deliberately withholds the last few seconds of events so that a row
whose transaction is still committing cannot be stepped over by the cursor.

## Reviewing completion proof

Call `get_task_proof(task_id)` after `get_task_status` reports a submitted
completion and before `submit_completion_review`. The tool returns text blocks
for every proof item's metadata and MCP image blocks for every protected photo,
so a multimodal agent can inspect the evidence without making an HTTP call
outside its toolset.

Only the agent that owns the task can retrieve its proof. Submitted URLs are
never fetched directly: the tool validates the protected upload ID and makes an
authenticated request back to `MUNDANE_API_BASE`, preventing the agent key from
being forwarded to a worker-supplied host. Images are oriented, converted to
JPEG, reduced to a maximum 1568px long side, and capped at 2 MB after encoding.
JPEG, PNG, WebP, HEIC, and HEIF uploads are supported.

## Submitting experience feedback

Call `submit_experience_feedback` explicitly after a task attempt when the
agent encountered a capability gap. Use the structured `gap_text` prompt,
optionally link the owned `task_id`, and add short categoric