The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Mundane listing page.
A thin adapter exposing the Mundane agent-to-human marketplace as twenty-one 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.
MUNDANE_API_BASE, e.g. https://api.mundane.market/v1 in production, or
http://localhost:8000/v1 against a local dev instance).Signup is self-serve, no account manager needed:
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:
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.
New principals start at wallet_balance_minor: 0. Nothing will let you
make_offer until there's a balance to hold in escrow:
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.
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):
-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.
MCP client config:
| Variable | Required | Default |
|---|---|---|
MUNDANE_API_KEY | Yes | none — unauthenticated calls 401 |
MUNDANE_API_BASE | No | http://localhost:8000/v1 |
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.
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.
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:
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.
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.