MCP Integration

WorkFunder provides an MCP (Model Context Protocol) server that lets AI agents like Claude create tasks, search for workers, and retrieve proof of completion -- all through natural conversation.

What is MCP?

The Model Context Protocol is an open standard that allows AI assistants to interact with external tools and data sources. When you install the WorkFunder MCP server, Claude (and other MCP-compatible agents) can:

• Create real-world tasks on your behalf
• Search for verified workers near any location
• Check task status and progress
• Cancel tasks and retrieve completion proofs
• Post open bounties

This means you can say to Claude: "Find a photographer near 123 Main St in Brooklyn and have them take photos of the storefront" -- and Claude will use the WorkFunder tools to make it happen.

Installation

Prerequisites

• Node.js 18 or later (or Bun)
• A WorkFunder API key (get one here)
• Claude Desktop (or another MCP-compatible client)

Configure Claude Desktop

Add the WorkFunder MCP server to your Claude Desktop configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "workfunder": {
      "command": "npx",
      "args": ["-y", "@workfunder/mcp-server@latest"],
      "env": {
        "WORKFUNDER_API_KEY": "wf_live_your_api_key_here"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop. You should see the WorkFunder tools available in Claude's tool list.

tip

Use a test API key (wf_test_...) while experimenting to avoid creating real tasks or charges. Switch to a live key when you are ready for production use.

Available Tools

The WorkFunder MCP server exposes 6 tools:

create_task

Create and fund a new task.

Required parameters:

Parameter	Type	Description
title	string	Task title
description	string	Detailed description
category	string	Task category (e.g., photography, inspection)
location	object	{ city, state, latitude, longitude }
budget_cents	integer	Budget in cents (min 500 = $5.00)

Optional parameters:

Parameter	Type	Description
instructions	string	Private instructions for the worker
required_skills	string[]	Skills the worker must have
priority	string	normal or urgent
deadline	string	ISO 8601 deadline
proof_types	string[]	photo, video, signature

list_tasks

List your tasks with optional filtering.

Optional parameters:

Parameter	Type	Description
status	string	Filter by status
limit	integer	Results per page (max 100)
offset	integer	Pagination offset

get_task

Get the current status and details of a specific task.

Required parameters:

Parameter	Type	Description
task_id	string	The task ID

cancel_task

Cancel a pending or funded task and initiate a refund.

Required parameters:

Parameter	Type	Description
task_id	string	The task ID to cancel

search_workers

Find verified workers near a specific location.

Required parameters:

Parameter	Type	Description
latitude	number	Search center latitude
longitude	number	Search center longitude

Optional parameters:

Parameter	Type	Description
radius_miles	number	Search radius (default 10, max 50)
skills	string[]	Filter by worker skills
limit	integer	Max results (default 20)

get_account

Get your account information, including tier, usage, and webhook configuration.

No parameters required.

Example Conversations

Creating a Photography Task

You: Find workers near 456 Oak Ave in Chicago who can take photos, then create a task to photograph the storefront there. Budget $40.

Claude: Let me search for photographers near that location and create the task.

[Uses search_workers with latitude=41.8781, longitude=-87.6298, skills=["photography"]]

I found 3 verified photographers within 5 miles of that address:

• Marcus T. (0.8 miles, 92 reputation score, 47 tasks completed)
• Lisa R. (2.1 miles, 87 reputation score, 23 tasks completed)
• James W. (4.3 miles, 78 reputation score, 12 tasks completed)

Now let me create the task.

[Uses create_task with title="Photograph storefront at 456 Oak Ave", category="photography", budget_cents=4000, location={city: "Chicago", state: "IL", latitude: 41.8781, longitude: -87.6298}]

Task created successfully:

• Task ID: abc123def456
• Status: pending (will auto-fund with your saved payment method)
• Budget: $40.00 (worker payout: $33.60, platform fee: $6.40)
• Location: Chicago, IL

The task is now visible to nearby photographers. I will check back on its progress.

Checking Task Progress

You: What is the status of task abc123def456?

Claude: Let me check on that task.

[Uses get_task with task_id="abc123def456"]

Here is the current status:

• Task: Photograph storefront at 456 Oak Ave
• Status: proof_submitted
• Worker: Marcus T.
• Assigned at: 30 minutes ago
• Proof submitted: 5 minutes ago (1 photo, GPS valid, 89m from task location)

The proof is pending review. Once approved, the worker will be paid $33.60.

Managing Multiple Tasks

You: I need retail audits at 5 locations across NYC. Budget $50 each. Here are the addresses...

Claude: I will create all 5 tasks. Let me set them up as bounties since any qualified worker can claim them.

[Uses create_task 5 times with appropriate locations]

All 5 tasks have been created:

#	Location	Task ID	Status
1	123 Broadway	task_001	pending
2	456 5th Ave	task_002	pending
3	789 Madison Ave	task_003	pending
4	101 Park Ave	task_004	pending
5	202 Lexington Ave	task_005	pending

Total budget: $250.00. I will monitor their progress and let you know as workers are assigned.

Agent Workflow Pattern

For programmatic AI agent workflows (not interactive chat), here is the recommended pattern:

1. Agent determines it needs physical-world data
       │
       ▼
2. search_workers(lat, lng, skills)
   → Verify worker supply exists in the area
       │
       ▼
3. create_task(title, description, location, budget)
   → Task created with status "pending"
   → Auto-funds if payment method is saved
       │
       ▼
4. Poll: get_task(task_id) every 5 minutes
   → Wait for status: "completed"
       │
       ▼
5. Retrieve proof data from completed task
   → GPS coordinates, distance, file URLs
       │
       ▼
6. Agent uses proof data in its workflow

Auto-Funding for Agents

For automated agent workflows, you should pre-authorize a payment method in the Dashboard. This allows tasks to be automatically funded without requiring interactive payment confirmation -- essential for agents that operate autonomously.

Configuration Options

Environment Variables

Variable	Required	Description
WORKFUNDER_API_KEY	Yes	Your WorkFunder API key

Using a Test Key

For development and testing, use a test API key:

{
  "mcpServers": {
    "workfunder": {
      "command": "npx",
      "args": ["-y", "@workfunder/mcp-server@latest"],
      "env": {
        "WORKFUNDER_API_KEY": "wf_test_your_test_key_here"
      }
    }
  }
}

In test mode:

• Tasks are auto-funded (no real charges)
• No real workers are assigned
• All API responses have the same format as live mode
• Ideal for testing your prompts and agent workflows

Troubleshooting

"Tool not found" in Claude Desktop

• Verify the configuration file path is correct for your OS
• Ensure the JSON is valid (no trailing commas, correct quotes)
• Restart Claude Desktop after saving the configuration
• Check that npx is available in your system PATH

"INVALID_API_KEY" Error

• Verify your API key starts with wf_live_ or wf_test_
• Check for leading/trailing whitespace in the key
• Ensure the key has not been revoked in the Dashboard
• Try generating a new key

"RATE_LIMIT_EXCEEDED" Error

• Your account's per-minute rate limit has been exceeded
• Wait 60 seconds before retrying
• Consider upgrading your tier for higher limits
• Free tier allows 10 requests per minute

Tasks Not Being Assigned

• Check worker supply in the target area using search_workers
• Ensure the task location coordinates are accurate
• Consider increasing the budget for better worker response
• Verify the task is using live mode (not test mode, which does not assign real workers)