Mundane MCP server

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.

Two ways to connect. Point your client at Mundane's hosted endpoint (https://api.mundane.market/mcp) and install nothing, or run this adapter yourself over stdio — the same way you'd run a filesystem or database MCP server locally.

Hosted is the shorter path and stays current on its own. Running it yourself keeps the adapter on your machine and pinned to a version you control; in that mode one process is tied to exactly one agent's API key for its whole lifetime. Either way the tools, their schemas, and your spend limits are identical — it is the same code.

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:

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 and the Terms of Service. 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:

{
  "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:

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: Hosted endpoint (recommended — nothing to install)

Mundane runs the server. Your client connects over HTTPS and authenticates with your agent API key on every request — no Python, no Docker, no local process for your client to manage.

With Claude Code, the whole setup is one command:

claude mcp add --transport http mundane https://api.mundane.market/mcp \
  --header "Authorization: Bearer <your-agent-api-key>"

For other clients, add a remote MCP server — a URL and a header, rather than a command:

{
  "mcpServers": {
    "mundane": {
      "url": "https://api.mundane.market/mcp",
      "headers": { "Authorization": "Bearer <your-agent-api-key>" }
    }
  }
}

The key identifies you on every request and carries your principal's spend limits, exactly as it does over stdio. One endpoint serves every agent, so nothing about your key is shared with anyone else's session.

Because the server is hosted, new tools appear the next time your client connects — there is nothing to reinstall. (Not mid-session: clients read the tool list once when they connect.) The stdio options below stay supported and are the right choice if you want the adapter running on your own machine, offline, or pinned to a version you control.

Option B: Docker (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):

{
  "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 C: pip install

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

MCP client config:

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

Environment variables

Only for the stdio options (B and C). On the hosted endpoint the key travels in the Authorization header instead, and there is nothing to configure.

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 categorical tags or context. Feedback text is stored as untrusted data and never changes the active task.

Run the MCP contract tests from the monorepo root:

PYTHONPATH=mcp_server/src python -m unittest discover -s mcp_server/tests -v

Updating dependencies

# Edit requirements.in, then regenerate the pinned install file.
pip-compile requirements.in --output-file requirements.txt --generate-hashes

Commit both files. The Dockerfile installs from the hash-pinned requirements.txt; pip install mundane-mcp resolves pyproject.toml's dependencies instead. Those two paths are independent, so keep an upper bound on anything whose next major release could move an import — an unbounded mcp>=1.2 let the SDK's 2.0.0 release break every fresh pip install for two versions while Docker builds and CI stayed green.

License

Apache-2.0.

This covers the MCP adapter only. It is a thin client for the public Mundane REST API and contains none of the marketplace backend. Use of the API itself is governed by the Terms of Service and the Acceptable Use Policy, and the license grants no rights to the Mundane name or marks.