众包任务管理MCP服务器

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

Wallet-native setup (one env var)

If you have a Solana wallet, you don't need to sign up at all — set GT_SOLANA_PAYER_SK and skip GT_API_KEY entirely. No wallet yet? Generate a keypair with the Solana CLI:

solana-keygen new --outfile ~/.config/solana/groundtruther.json
# GT_SOLANA_PAYER_SK accepts that file's contents verbatim (a JSON byte array)
# or a base58-encoded secret key.

{
  "mcpServers": {
    "groundtruther": {
      "command": "uvx",
      "args": ["groundtruther-mcp"],
      "env": {
        "GT_API_URL": "https://api.groundtruther.io/api/v1",
        "GT_SOLANA_PAYER_SK": "<JSON byte array or base58 secret>"
      }
    }
  }
}

On startup the server signs a SIWS (Sign-In With Solana) challenge with your key — locally, over the Anza off-chain message format; the key never leaves your machine and the signed payload can never be a transaction — and GroundTruther auto-provisions an escrow-enabled agent named agent-<pubkey prefix> with your wallet as its default payer, mints an API key, and the server stores it with 0600 permissions in ~/.groundtruther/credentials.json. You'll see a log line like authenticated as agent-AbCdEfGh via wallet ... on startup — it goes to stderr, which most MCP clients hide behind a log viewer. The client validates every challenge before signing (correct GT host, your own address, ASCII-only, nonce present, not transaction-shaped) and refuses loudly otherwise.

• The API key is THE credential. /auth/wallet/verify returns only the API key (no session JWT); everything the agent surface does authenticates with it, and rotating it (below) is the complete revocation story.
• Key rotation: delete the credentials entry (or hit a 401) and the server re-signs a challenge — each re-verify mints a fresh API key and revokes the old one. A 401 from a rotated/revoked key triggers exactly one automatic re-auth before failing loudly. A request timeout on an authenticated call gets the same one-shot re-auth (a stale key can surface as a stall instead of a clean 401).
• Spend caps: auto-provisioned agents start with default daily/weekly spend limits, enforced on both custodial and on-chain missions — a leaked API key can't drain your wallet mission-by-mission.
• Settings ceiling: wallet-native accounts have no webapp password. Settings beyond what the API exposes (raising spend caps, renaming the agent) are founder/concierge changes for now — contact the GroundTruther team.

Get an API Key (classic setup)

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 (wallet-native agents are escrow-enabled at provisioning; classic agents are concierge — 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.

Funding the wallet (honest devnet notes): SOL for transaction fees is self-serve — solana airdrop 1 <your pubkey> --url devnet. Test-USDC is concierge for now: there is no faucet, so ask the GroundTruther team for a top-up before your first escrow mission. If you try to fund with an empty wallet, the error tells you exactly what's missing (SOL vs USDC, with current balances) — and note the mission is still created but unfunded in that case: retry with a new request_qa_test after topping up, or clean up with cancel_mission(task_id) (the error message includes the id).

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

In-process use (no stdio server)

The MCP stdio transport is the supported integration, but every tool is a plain async function you can import and call directly — useful for test harnesses and embedding:

from groundtruther_mcp.tools_qa import request_qa_test, get_qa_result

result = await request_qa_test(staging_url="https://staging.example.com",
                               steps='[{"instruction": "...", "expected": "..."}]')

Configuration still comes from the environment (GT_API_KEY/GT_API_URL, or wallet-native via GT_SOLANA_PAYER_SK — call await groundtruther_mcp.wallet_auth.ensure_wallet_credentials() once at startup to run the same auto-auth bootstrap the server performs). Tools return JSON strings, errors as {"error": "..."}.

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