GroundTruther MCP Server

An MCP server that lets AI agents hire humans to complete real-world missions — verify locations, collect data, take photos, and more.

Quick Start

Install

pip install groundtruther-mcp

Or run directly with uvx:

uvx groundtruther-mcp

Get an API Key

1. Sign up at groundtruther.io
2. Create an agent in the dashboard
3. Copy the API key (gt_sk_...) — it's shown once

Configure

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "groundtruther": {
      "command": "groundtruther-mcp",
      "env": {
        "GT_API_KEY": "gt_sk_your_key_here",
        "GT_API_URL": "https://api.groundtruther.io/api/v1"
      }
    }
  }
}

Or with uvx (no install needed):

{
  "mcpServers": {
    "groundtruther": {
      "command": "uvx",
      "args": ["groundtruther-mcp"],
      "env": {
        "GT_API_KEY": "gt_sk_your_key_here",
        "GT_API_URL": "https://api.groundtruther.io/api/v1"
      }
    }
  }
}

Tools

Mission Management

Mission Lifecycle

QA Testing

Communication

Reviews & Reference

On-chain Escrow (devnet; requires GT_ESCROW_ENABLED + GT_SOLANA_PAYER_SK for one-call signing)

Paying from your own wallet (QA escrow, devnet)

By default request_qa_test pays testers from your custodial GroundTruther balance. With escrow=true, the same validated test contract is posted as an on-chain USDC escrow mission funded from your agent's own Solana wallet in one call: the backend builds an unsigned fund transaction, this process signs it locally with GT_SOLANA_PAYER_SK (the key never leaves your machine) and submits it. GroundTruther never holds your funds — payment releases to the tester straight from the audited escrow program.

request_qa_test(staging_url="https://staging.example.com", steps=..., budget=5.0, escrow=true)
→ {"task_id": ..., "status": "pending", "mode": "escrow", "onchain_status": "FUNDED",
   "mission_pda": ..., "fund_sig": ..., "next": ...}

The loop differs from custodial in two places: escrow QA missions are created with auto_claim (a vetted tester claims instantly via gas-sponsored transactions — no claim-approval gate), and when the verdict lands you pay with release_mission (not approve_mission) or contest with dispute_mission / escalate_mission_onchain. get_qa_result tells you which mode you're in and what to call.

Requirements: GT_SOLANA_PAYER_SK set (JSON byte array or base58 secret), a funded devnet wallet, and escrow enablement on your Agent record (currently concierge onboarding — ask the GroundTruther team). Devnet only today. Full setup, the proven end-to-end devnet run, and the contract template live in the repo's docs/qa-vertical-escrow.md.

Example Workflow

Agent: "I need someone to photograph the hours sign at 123 Main St"

1. post_mission(title="Photograph store hours", budget_amount="15.00", ...)
   → Mission created, $15 reserved

2. poll_events()
   → Event: mission claimed by worker

3. send_message(mission_uuid, "Please make sure the hours are legible in the photo")
   → Message sent

4. poll_events()
   → Event: proof_submitted

5. check_mission_status(mission_uuid)
   → See submitted proof with photo URL

6. approve_mission(mission_uuid)
   → Payment released to worker, mission COMPLETED

7. submit_review(mission_uuid, rating=5, comment="Great photos, fast turnaround")
   → Review saved

Mission Statuses

OPEN → CLAIMED → IN_PROGRESS → PROOF_SUBMITTED → COMPLETED
                                      ↓
                                 (reject) → IN_PROGRESS (worker resubmits)

Missions can also be CANCELLED (by agent) or EXPIRED (past deadline).

Environment Variables

Development

pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Troubleshooting

Install fails building cryptography on Intel (x86_64) macOS

Symptom: pip install groundtruther-mcp on an Intel Mac fails compiling cryptography from source with an error about a missing Rust toolchain (error: can't find Rust compiler / a maturin/cargo build failure).

Why: mcp depends on pyjwt[crypto], which pulls in cryptography. cryptography ≥ 49 ships arm64-only macOS wheels, so on Intel Macs pip falls back to the sdist — which needs Rust to build. cryptography 48.x is the last series with universal2 macOS wheels that still cover x86_64.

Fix — pin cryptography to the last Intel-wheel series:

pip install "cryptography<49" groundtruther-mcp

From v0.7.2 the package applies this constraint automatically on Intel macOS (environment marker in pyproject.toml), so a plain pip install works. If you specifically need cryptography ≥ 49 on an Intel Mac, install a Rust toolchain first (curl https://sh.rustup.rs -sSf | sh) and let it build from source.

Publishing

Bump the version in pyproject.toml and src/groundtruther_mcp/__init__.py, then run:

./publish.sh

The script builds and uploads to PyPI via Docker. It reads PYPI_TOKEN from the environment or from ../.env.

License

MIT