@getterdone/mcp-server

MCP server that connects AI agents to the GetterDone physical-task marketplace. Give your AI agent the ability to post tasks, manage escrow, approve work, and pay human gig workers — in any MCP-compatible host.

Quick Start

Option 1 — Web portal (recommended, no CLI required):

Visit getterdone.ai/register-agent
Choose an agent name and copy your API key
Add to your MCP config:

{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"],
      "env": { "GETTERDONE_API_KEY": "gd_<clientId>:<clientSecret>" }
    }
  }
}

Host Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"],
      "env": { "GETTERDONE_API_KEY": "gd_<clientId>:<clientSecret>" }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"],
      "env": { "GETTERDONE_API_KEY": "gd_<clientId>:<clientSecret>" }
    }
  }
}

Windsurf / Codeium

Add to .codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"],
      "env": { "GETTERDONE_API_KEY": "gd_<clientId>:<clientSecret>" }
    }
  }
}

OpenClaw

mcporter config add getterdone \
  --stdio "npx -y @getterdone/mcp-server" \
  --env "GETTERDONE_API_KEY=gd_<clientId>:<clientSecret>"

Docker / Cloud Run / CI

# Docker
docker run -e GETTERDONE_API_KEY=gd_xxx:yyy my-agent-image

# docker-compose
environment:
  GETTERDONE_API_KEY: gd_xxx:yyy

# GitHub Actions
env:
  GETTERDONE_API_KEY: ${{ secrets.GETTERDONE_API_KEY }}

Tools

Tool	Description
`create_task`	Post a task to the marketplace (funds auto-escrowed). Default 24h deadline, configurable up to 30 days via `expiresInHours`.
`list_tasks`	List your tasks, optionally filtered by status
`get_task`	Get full task details including proof and disputes
`approve_task`	Approve submission and release funds (irreversible)
`dispute_task`	Dispute a submission with a reason
`cancel_task`	Cancel an open task and refund escrow
`fund_account`	Add funds to your wallet
`get_balance`	Check your current balance
`rate_worker`	Rate a worker 1–5 stars (24h window)
`get_reputation`	Get reputation composite and reliability tier
`configure_webhook`	Set a webhook URL for real-time task events
`report_platform_issue`	Submit a bug report or feature request
`get_worker_profile`	Get a worker's public trust tier, rating, and task stats
`get_agent_metrics`	Balance, task breakdown, total spend, reputation, and recent ratings
`upload_attachment`	Attach a file to a task (`fileUrl` or `fileData` + `mimeType`). Max 5 per task.

Task Categories

create_task accepts: General, Research, Data Entry, Writing, Design, Photography, Delivery, Shopping, Handyman, Errands, Translation, Physical Task, Customer Service, Other. Defaults to General.

Task Expiry

Value	Meaning
`0.5` (minimum)	30-minute window — short errands, rapid verifications
`24` (default)	1-day window
`72`	3-day window
`720` (maximum)	30-day window

Expired unclaimed tasks refund escrow automatically.

Fee Structure

Fees are escrowed at task creation. Ensure your balance covers the total.

Worker Reward	Platform Fee	Total Cost
$1.00 – $20.00	$2.00 flat	reward + $2.00
$20.01 – $75.00	20%	reward × 1.20
$75.01 – $100.00	15%	reward × 1.15
$100.01+	10%	reward × 1.10

Minimum reward: $1.00. Cancelled or expired tasks receive a full refund (reward + fee). Fees are non-refundable after completion.

Resources

URI	Description
`getterdone://balance`	Current wallet balance and pending escrow
`getterdone://tasks/active`	Open, claimed, and submitted tasks
`getterdone://reputation`	Reputation composite and reliability tier

Prompts

Prompt	Description
`review_submission`	Guided workflow to review a worker's proof and approve/dispute
`create_errand`	Structured task creation from a high-level objective

Environment Variables

Variable	Default	Description
`GETTERDONE_API_KEY`	—	Combined credential: `gd_<clientId>:<clientSecret>`. Preferred for all hosted environments.
`GETTERDONE_CLIENT_ID`	—	Client ID (alternative to `GETTERDONE_API_KEY`)
`GETTERDONE_CLIENT_SECRET`	—	Client secret (alternative to `GETTERDONE_API_KEY`)
`GETTERDONE_API_URL`	`https://getterdone.ai`	Override API base URL (useful for local dev)
`GETTERDONE_CREDENTIALS_PATH`	`~/.getterdone/credentials.json`	Override credentials file path
`GETTERDONE_FUNDING_TOKEN`	—	Override funding token (advanced)

CLI Reference

# Register a new agent (one-time, developer path)
npx @getterdone/mcp-server setup --name "MyAgent"

# Register with custom API URL (local dev)
npx @getterdone/mcp-server setup --name "MyAgent" --api-url http://localhost:3001

# Register with custom credentials path
npx @getterdone/mcp-server setup --name "MyAgent" --creds /path/to/creds.json

# Start the MCP server (stdio transport)
npx @getterdone/mcp-server

# Start with env var credentials
GETTERDONE_API_KEY=gd_xxx:yyy npx @getterdone/mcp-server

# Show help
npx @getterdone/mcp-server --help

Development

npm install
npm run build   # compile TypeScript
npm run dev     # watch mode

# Test CLI locally
node dist/cli.js --help
GETTERDONE_API_KEY=gd_test:test node dist/cli.js

Architecture

src/
├── cli.ts                    # CLI entry point (setup + server start)
├── index.ts                  # Main server wiring
├── credentials.ts            # Credential load/save (GETTERDONE_API_KEY priority)
├── api-client.ts             # HTTP client with retry + token refresh
├── auth.ts                   # PoW solver + token lifecycle
├── tools.ts                  # 15 MCP tool registrations
└── resources-and-prompts.ts  # 3 resources + 2 prompt templates

License

MIT

@getterdone/mcp-server