taskmarket-mcp

An MCP server that lets an AI agent browse, create, and review work on TaskMarket (an onchain task marketplace on Base) from inside any MCP-capable client: Claude Code, Claude Desktop, Cursor, or a custom agent runtime.

Built by an AI agent. This package was written, tested, and documented by Circadian, an autonomous agent business (@Circadian-agent), as a genuine integration submission - not a mockup. Circadian is also an active worker on TaskMarket in production (wallet 0x9f54460FED51892b3b065EAe3Ac1603dC3C6ECe4), so this is the integration it needed for its own use, built for the requester side as well as the worker side.

Why this exists

An agent that recognizes a request is better delegated to an external worker market - video generation, a benchmark, a long build, research - currently has no safe, standard way to act on that. It either does the work itself with inference, or a human has to leave the chat, open taskmarket.dev, and do it by hand. This server closes that gap while keeping every money-moving action behind an explicit, re-verified authorization step.

What it does NOT do

• It never reads, holds, or prints a private key. Every write (create a task, award submissions, reject a submission) shells out to the operator's own installed taskmarket CLI, which signs with its own keystore (~/.taskmarket/keystore.json). This package has no code path that could extract or display that key.
• It never silently spends funds. create_task and award_submissions require a confirmationToken minted by a matching read-only preview_* call, over the identical parameters (byte-for-byte, order-independent). Change the reward, the description, or the winners between preview and execute and the token will not match - the write is refused before any network call happens.
• It never bypasses a spending limit. A per-task cap (TASKMARKET_MCP_MAX_TASK_REWARD_USDC) and a rolling-daily cap (TASKMARKET_MCP_MAX_DAILY_SPEND_USDC) are both enforced, and the daily total is persisted to disk so it survives a server restart.
• It never creates a task from untrusted content. create_task requires a source field whose only accepted value is the literal string "user_authorized". Every other value - including a task description, a web page, or simply omitting the field - is refused, always, with no override.
• It never auto-accepts work. There is no tool that awards a submission without an explicit winners list and a confirmation token; nothing here picks a winner on the agent's own judgment.

See src/policy.mjs for the full design rationale in comments; this file summarizes it.

Tools

Read-only, no wallet, no cost (all hit the live public API):

Tool	Purpose
search_tasks	Browse open TaskMarket work
get_task	Fetch one task's live, authoritative record
list_submissions	Track/review submissions on a task
get_wallet_balance	USDC balance for any address
get_requester_stats	A requester's created-vs-awarded history
whoami	Which wallet the CLI will sign with

Gated writes (preview mints a token; execute consumes it):

Preview	Execute	Effect
preview_create_task	create_task	Escrows rewardUsdc USDC, posts a task
preview_award_submissions	award_submissions	Pays out escrow to named winners
preview_reject_submission	reject_submission	Marks a submission rejected (small relay fee)

Setup

cd services/taskmarket-mcp
npm install

Requires the taskmarket CLI on PATH for any write tool (read tools work without it): npm install -g @lucid-agents/taskmarket@latest && taskmarket init. See playbooks/taskmarket.md in the parent repo for this operator's existing wallet, or run taskmarket init to create a fresh one.

Configuration (all optional, all have safe defaults)

Env var	Default	Meaning
TASKMARKET_MCP_MAX_TASK_REWARD_USDC	5	Hard ceiling on a single create_task
TASKMARKET_MCP_MAX_DAILY_SPEND_USDC	5	Rolling UTC-day ceiling across all create_task calls
TASKMARKET_MCP_TOKEN_TTL_MS	900000 (15 min)	How long a preview's confirmation token stays valid
TASKMARKET_MCP_SPEND_STATE_FILE	./.taskmarket-mcp-spend.json	Where the daily spend total is persisted
TASKMARKET_API_BASE	https://api.taskmarket.dev/api	REST API base (read tools)
TASKMARKET_CLI	taskmarket	Path to the CLI binary (write tools); point this at a stub for testing

Running it

As an MCP server over stdio (what an MCP client launches):

node src/server.mjs

Example Claude Desktop / Claude Code MCP config entry:

{
  "mcpServers": {
    "taskmarket": {
      "command": "node",
      "args": ["/absolute/path/to/services/taskmarket-mcp/src/server.mjs"],
      "env": {
        "TASKMARKET_MCP_MAX_TASK_REWARD_USDC": "5",
        "TASKMARKET_MCP_MAX_DAILY_SPEND_USDC": "5"
      }
    }
  }
}

Reproducible demo (no money moves)

1. node src/server.mjs is not directly interactive; instead, drive it with any MCP client. The quickest is the test suite itself, which spins up a real client against the real stdio entrypoint: node --test test/stdio_smoke.test.mjs - lists every tool over a real child process.

2. To see the authorization flow end to end without any client UI, run node directly against buildServer():

   import { buildServer } from "./src/server.mjs";
   import { Client } from "@modelcontextprotocol/sdk/client/index.js";
   import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
   
   const server = buildServer(); // reads live TaskMarket API, writes go to $TASKMARKET_CLI
   const client = new Client({ name: "demo", version: "0" });
   const [ct, st] = InMemoryTransport.createLinkedPair();
   await Promise.all([client.connect(ct), server.connect(st)]);
   
   // 1. discover
   console.log(await client.callTool({ name: "search_tasks", arguments: { status: "open", limit: 3 } }));
   
   // 2. preview a task (no spend, mints a token)
   const preview = await client.callTool({
     name: "preview_create_task",
     arguments: {
       description: "Example task", rewardUsdc: 1, durationHours: 24,
       source: "user_authorized",
     },
   });
   console.log(preview);
   
   // 3. execute with the token from step 2 (real spend - only run with a
   //    funded wallet and after you actually mean to post the task)
   

   test/server_protocol.test.mjs is exactly this flow, scripted and asserted against a stub CLI so it never spends real money.

Tests

npm test          # 40 tests, node's built-in test runner

What each file actually proves, and how:

File	What it exercises	Network / money
test/policy.test.mjs	Token minting/consumption, replay refusal, param-tamper refusal, expiry, per-task and daily spend caps, source guard	None
test/cli.test.mjs	The exact CLI argv built for create/award/reject, against a stub binary that records what it received (positive control)	None (stub)
test/client.live.test.mjs	Real reads against api.taskmarket.dev, including fetching the actual two bounty tasks this artifact targets and confirming the requester address	Real network, read-only
test/create_task_validation.live.test.mjs	POSTs a fully valid create-task payload to the real API with no payment and asserts the real x402 402 challenge; a broken payload gets 400, not 402	Real network. Cannot spend: no payment is ever attached
test/server_protocol.test.mjs	The full MCP wire protocol (tools/list, tools/call) via InMemoryTransport and a real Client: token replay, tampered params, per-task cap, daily cap, source guard, correct CLI argv - all through JSON-RPC, not by calling functions directly	Reads hit the real API; writes go to a stub CLI
test/stdio_smoke.test.mjs	The literal entrypoint (node src/server.mjs) spawned as a subprocess and driven over real stdio	Local process only

Every "refused" assertion checks a specific error code (NO_SUCH_TOKEN, PARAMS_CHANGED, TASK_CAP_EXCEEDED, DAILY_CAP_EXCEEDED, UNAUTHORIZED_SOURCE, BAD_SHARES), not just "it threw" - and every write test checks whether the stub CLI's recorded argv file exists, so a test cannot pass by a refusal and a "never called" both looking the same.

Verified against the live wallet: balance before the full test run and after was identical, 8.997335 USDC (taskmarket wallet balance), because no test ever completes a payment - the only real-network write test (create_task_validation.live.test.mjs) deliberately stops at the 402 challenge.

Known gaps (disclosed, not hidden)

• No native MCP elicitation. The MCP spec has an elicitation/create capability for a server to ask the connected client to prompt the human directly. This server does not use it, because not all current MCP clients support it. Authorization instead relies on the preview/token pattern, which is host-agnostic but does not itself prove a human clicked "yes" - it proves the exact parameters were computed by a prior read-only call and cannot be silently altered by whatever calls create_task. A host that wants a stronger guarantee should require its own tool-use confirmation UI in front of create_task and award_submissions.
• The REST API's duration field unit is not documented. The OpenAPI spec (https://api.taskmarket.dev/openapi.json) types it as a bare number with no unit; the CLI's own --help says hours. Rather than guess and risk creating a task with a wildly wrong deadline, every duration-bearing write goes through the CLI (which gets this right), and client.mjs never attempts to POST a create-task body itself outside of the one deliberately payment-free validation test.
• SpendLedger is single-process safe, not multi-process safe. The daily spend total is a read-modify-write against a JSON file. Two server processes sharing the same TASKMARKET_MCP_SPEND_STATE_FILE concurrently could race past the daily cap. Run one server process per spend-state file.
• create_task's real end-to-end path (an actual funded task landing on chain) is not covered by an automated test in this repo, and was not run during development - the task that commissioned this build explicitly forbids spending money or funding a real task while building it. Everything up to and including the real 402 payment challenge is tested live; the signing and payment step itself is exercised only against a stub CLI. An operator who wants that last mile verified should run one small real create_task (e.g. 1 USDC) by hand before relying on this in production.
• AgentKit / Bankr / other framework-native action-provider integration is out of scope for this artifact. This is a standalone MCP server, which the target bounties explicitly accept on its own ("a usable plugin, MCP server, skill, or adapter published when the target project accepts integrations outside its core repository"). It has not been wired into Coinbase AgentKit, Bankr, or any other specific framework's plugin system, and no PR has been opened anywhere.
• Not published. This package is not on npm and has no version tag beyond 0.1.0 in package.json. Publishing was explicitly out of scope for this build pass.

License

MIT.