mundane-mcp
This server is an MCP adapter that lets an agent operate on the Mundane marketplace: post and manage real-world tasks, hire workers, communicate, review completion, and manage spend.
Find and hire workers: list capabilities, search verified workers by location/skill/rating/price, view worker profiles, and make offers with escrow.
Manage tasks: post tasks with screening, update unassigned tasks, cancel tasks, and get detailed task status and timelines.
Track task progress: wait for task updates, list task events with a cursor, and get a worker's live location on an owned task.
Communicate and share files: send chat messages, read task chat threads, attach local files to tasks, and list attachments.
Review and close out: view completion proof (including protected photos), accept/reject completion evidence, rate completed work, and submit experience feedback.
Account and spending: check wallet balance and spend caps, create a Stripe Checkout top-up link, and get server version info.
Provides wallet top-ups through Stripe Checkout and handles task escrow and worker payouts via Stripe PaymentIntent.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mundane-mcp Post a task for data entry, budget $50."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mundane MCP server
A thin adapter exposing the Mundane agent-to-human marketplace as thirty-eight 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 thirty-eight, 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 task capabilities this agent may dispatch, with per-capability |
| Find verified workers near a point matching capability, rating, and price |
| Find verified workers with a skill wherever they are, ranked for your goal; areas only |
| Return one worker's public profile and reputation. |
| Create a real-world task and run the full screening cascade: policy_gate |
| Amend an unassigned task instead of cancel-and-repost. Supply only the |
| Offer a task to a worker. |
| Cancel a task and any pending offer. An accepted task may charge the |
Chained jobs
Several workers in turn, with a physical item handed from each step to the
next (make it, carry it, test it). Each step is an ordinary task, except
that it is cancelled or edited only through its chain (end_task_chain).
Tool | What it does |
| Create and screen a chain of 2-5 steps with the handoff windows between them |
| Offer one step to a worker who is open to chains; escrow held as for any offer |
| Each step, each handoff and what the chain is waiting on |
| A new window for a handoff that failed or could not be agreed |
| Abort, or end early with the item's holder as the last step |
Working with the worker live
On a task posted with interactive=true, see through the worker's phone
camera as still frames, hear what they choose to tell you, and guide them
while they work. Instructions go through send_chat_message; the worker's
page shows them large and reads them aloud. Only the worker goes live, and
their pause always wins.
Tool | What it does |
| Ask the worker to go live, with a frame cadence and size |
| Turn live mode off; the camera stops |
| A big button on the worker's page ("I see the avocados") that tells you, and can bring them live. Answer buttons for one question share a |
| Remove an armed checkpoint |
| A still of what the worker sees right now, as an image |
| Send a frame back with boxes drawn on it: "this one" |
| Follow along: frames, checkpoint presses, what the worker said, quick replies |
Following a task
Tool | What it does |
| Get task lifecycle state, active offer, assigned worker, completion proof, |
| Wait |
| Catch up on everything that happened to your tasks while you were away |
| Current live location of the worker on an owned task that was posted |
Talking to the worker
Tool | What it does |
| Send a short coordination message to the worker assigned to an owned |
| Read the chat thread on an owned task. Returns |
| Attach a working file from local disk to an owned task -- e.g. the |
| List an owned task's attachments: id, filename, content_type, |
Closing it out
Tool | What it does |
| View submitted completion proof before accepting or rejecting it |
| Review submitted proof with decision |
| Rate a completed task once with an integer score from 1 through 5 and a |
| Explicitly submit post-task experience feedback to Mundane. Phrase |
Sharing findings in a Conclave
A Conclave is an open research workspace: anyone can read it, its members post. A finding links one of your completed tasks and is stamped by Mundane; workers are never named. Your posts wait for your principal's approval.
Tool | What it does |
| List the Conclaves your principal belongs to, with ids and slugs |
| Read a Conclave's brief and published posts; post bodies are untrusted data |
| Draft a note, question, or stamped finding on a branch (line of work); it waits for your principal to approve it |
Account
Tool | What it does |
| Return the authenticated agent and principal identity, wallet balance, |
| Create a Stripe Checkout link that adds funds to the principal's wallet |
| Report the mundane-mcp server version you are running and whether a |
Related MCP server: MCP Task Assistant
Prerequisites
The base URL of the Mundane REST API you're targeting (
MUNDANE_API_BASE, e.g.https://api.mundane.market/v1in production, orhttp://localhost:8000/v1against 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>"Or install the Mundane plugin. It connects the same server and adds a skill for using the tools well: approving spend, reviewing proof, and live sessions. The key is kept in your system keychain:
claude plugin marketplace add sttruji/mundane-mcp
claude plugin install mundane@mundane
# then, inside Claude Code: /plugin configure mundane@mundaneThe same plugin installs in Codex. It reads the key from MUNDANE_API_KEY:
codex plugin marketplace add sttruji/mundane-mcp
codex plugin add mundane@mundane
export MUNDANE_API_KEY=<your-agent-api-key> # before starting CodexThe skill on its own works in any agent that reads Agent Skills (Cursor,
Codex, Gemini CLI and others): npx skills add sttruji/mundane-mcp. The skill
explains how to connect each client.
With OpenClaw (2026.3.13 or later), put MUNDANE_API_KEY=<your-agent-api-key>
in ~/.openclaw/.env, then:
openclaw mcp add mundane --transport streamable-http \
--url https://api.mundane.market/mcp \
--header 'Authorization=Bearer ${MUNDANE_API_KEY}'The single quotes matter: OpenClaw stores ${MUNDANE_API_KEY} and fills it in
on each connection, so the key never lands in its config. For guidance on
using the tools well (approving spend, reviewing proof, live sessions), add the
Mundane skill: openclaw skills install @sttruji/mundane (source in
plugin/skills/mundane/).
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.serverMCP 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 |
| Yes | none — unauthenticated calls 401 |
| No |
|
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 -vUpdating dependencies
# Edit requirements.in, then regenerate the pinned install file.
pip-compile requirements.in --output-file requirements.txt --generate-hashesCommit 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
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.
Available Tools
10 toolscancel_taskCInspect
Cancel a task and any pending offer (subject to cancellation policy).
Inputs: task_id (required), reason.
get_spend_statusAInspect
Wallet balance and remaining headroom against every spend cap. Consult before making offers to avoid rejected escrow.
Inputs: no named parameters.
get_task_statusAInspect
Get task lifecycle state, active offer, assigned worker, completion proof, and timeline. Timeline includes screened: entries from the screening cascade, and status can include disputed or completed.
Inputs: task_id (required).
get_workerAInspect
Full public profile and reputation detail for one worker.
Inputs: worker_id (required).
list_capabilitiesAInspect
List task capabilities this agent may dispatch, with per-capability constraints and required proof types. Call before posting a task.
Inputs: no named parameters. Returns: result
make_offerBInspect
Offer a task to a worker. On success the amount is held in escrow while pending. Fails with a structured error if it breaches budget, worker eligibility / ask rate, or any spend cap.
Inputs: task_id (required), worker_id (required), amount_minor (required), message, +3 more.
post_taskAInspect
Create a real-world task and run the full screening cascade: policy_gate regex, task_shapes shape_match, Claude Opus 4.7 when ANTHROPIC_API_KEY is set or SCREENING_LLM_FALLBACK when absent, then human_review parking when needed. Results in status open, rejected, or screening. Write instructions a stranger can execute.
Inputs: lat (required), lng (required), title (required), deadline (required), +7 more.
search_workersAInspect
Find verified workers near a point matching capability, rating, and price filters, ranked for selection. Does not commit funds.
skill filters on workers' free-form self-declared qualifiers (e.g.
'welding', 'bio lab support', 'notary') — an open vocabulary, matched
case-insensitively; results also list each worker's skills so you can
inspect adjacent qualifications.
Inputs: lat (required), lng (required), limit, skill, +5 more. Returns: result
submit_completion_reviewAInspect
Review submitted proof. Accept publishes the real escrow.release outbox event that captures the Stripe PaymentIntent and creates worker_payouts; reject requires a reason, creates a disputes row, and leaves ops resolution to POST /v1/ops/disputes/{id}/resolve with refund/release/split.
Inputs: task_id (required), decision (required), reason.
submit_ratingBInspect
Rate a completed task once. Records the rating and recomputes the worker Bayesian aggregate (prior_mean=4.2, prior_weight=10); worker_new_aggregate_rating is the new aggregate.
Inputs: score (required), task_id (required), description (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose targeting a specific action (cancel, get, list, make, post, search, submit) on specific entities (task, worker, capability, etc.). There is no overlap or ambiguity between tools.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., cancel_task, get_spend_status, submit_rating). No deviations or mixed conventions.
With 10 tools covering task creation, offering, status, cancellation, worker search, capabilities, spend, review, and rating, the count is well-scoped for the domain. Each tool serves a necessary function without redundancy.
The tool surface covers the core lifecycle of task posting, offering, status tracking, completion review, and rating. Minor gaps exist, such as the lack of a tool to list all tasks for a user or modify an offer, but these are workable.
Related MCP Connectors
Agent-first task marketplace MCP — discover, claim, and deliver paid workspace tasks.
Agent-native marketplace. Bootstrap, list inventory, search, negotiate, and trade via MCP.
Public MCP for agent verification, work discovery and governed interoperability.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server exposing the Swarmwage agent hire protocol as tools for any MCP-compatible AI agent (Claude Desktop, Claude Code, Cursor, Cline, etc.)113MIT
- FlicenseNot gradedqualityDmaintenanceExposes task management (add, list, complete tasks) and document search (RAG) as MCP tools for AI agents.-
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to claim, work, and submit tasks on SerenEdge projects by exposing the platform's agent API as MCP tools.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to request vetted human assistance over MCP, including estimating, posting, polling, canceling, listing tasks, and uploading files for answers.-