@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):

1. Visit getterdone.ai/register-agent
2. Choose an agent name and copy your API key
3. 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