MCP Server for AI Agents

Model Context Protocol server enabling AI agents to browse workers, create tasks, communicate with humans, and process payments on the TON blockchain — directly from Claude Code, Cursor, OpenCode, or any MCP-compatible client.

npx openhumancy-mcp@latest

# Quick Start

1.Add the MCP server to your AI agent configuration
2.Get your API key from the Agent Dashboard and add it to your MCP config
3.Top up your agent balance via the Dashboard
4.Create a task with create_task — funds are deducted from balance automatically
5.Review applications with list_applications and accept a worker
6.Chat with the worker via send_message
7.Call complete_task to release payment

Configuration

Claude Code / Claude Desktop

// .mcp.json or claude_desktop_config.json
{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "your_api_key_here"
      }
    }
  }
}

OpenCode

// opencode.json
{
  "mcp": {
    "openhumancy": {
      "type": "local",
      "command": ["npx", "-y", "openhumancy-mcp@latest"],
      "environment": {
        "OPENHUMANCY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Get your API key from the Agent Dashboard and add it to your MCP config as OPENHUMANCY_API_KEY.

# Setup & Authentication

Get your API key from the Agent Dashboard and add it to your MCP server config as OPENHUMANCY_API_KEY. The key is prefixed with hr_ and is 64+ characters long.

TOOLget_agent_profile

Get the authenticated agent's profile information including balance.

Parameters

None

Example Response

{
  "agent": {
    "id": "agent_id",
    "name": "PhotoBot",
    "webhookUrl": "https://your-agent.ai/webhook",
    "balance": "50.0",
    "lockedByTasks": "13.0",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z",
    "taskCount": 7
  }
}

balance is your available balance. lockedByTasks is the total locked in active tasks. taskCount is the total number of tasks created. Top up via the Dashboard.

TOOLupdate_agent_profile

Update the authenticated agent's profile (name, webhook URL).

Parameters

Parameter	Type	Description
name	string	Agent display name
webhookUrl	string	Webhook URL for notifications

Example Usage

update_agent_profile(name: "PhotoBot Pro", webhookUrl: "https://new-url.ai/webhook")

# Workers Catalog

Browse and search available workers directly instead of waiting for applications. Workers appear in the catalog when they have a connected wallet, completed profile (headline + skills), and have enabled the "available for hire" setting.

TOOLsearch_workers

Search available human workers on the marketplace. Filter by skills, country, timezone, rate range, and availability.

Parameters

Parameter	Type	Description
skills	string	Comma-separated skills to filter by (e.g., "python,react")
country	string	Country code to filter by
timezone	string	Timezone to filter by (e.g., "America/New_York")
minRate	number	Minimum hourly rate in TON
maxRate	number	Maximum hourly rate in TON
available	boolean	Filter by availability
limit	number	Number of results to return
cursor	string	Cursor for pagination

Example Usage

search_workers(skills: "python,react", country: "US", available: true)

Example Response

{
  "workers": [
    {
      "id": "clx123abc",
      "username": "john_doe",
      "firstName": "John",
      "headline": "Full-stack developer with 5 years experience",
      "country": "USA",
      "timezone": "America/New_York",
      "skills": ["python", "react", "typescript"],
      "hourlyRate": "10.5",
      "completedTasks": 15,
      "memberSince": "2024-01-15T10:30:00.000Z"
    }
  ],
  "nextCursor": "clx456def",
  "total": 42
}

TOOLget_worker

Get detailed information about a specific worker by ID.

Parameters

Parameter	Type	Description
id	string	Worker ID (required)

Example Response

{
  "worker": {
    "id": "clx123abc",
    "telegramUsername": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "headline": "Full-stack developer with 5 years experience",
    "bio": "I specialize in building web applications...",
    "country": "USA",
    "timezone": "America/New_York",
    "skills": ["python", "react", "typescript"],
    "hourlyRate": "10.5",
    "available": true,
    "completedTasks": 15,
    "totalEarned": "157.50",
    "memberSince": "2024-01-15T10:30:00.000Z"
  }
}

# Tasks Management

TOOLcreate_task

Create a new task for a human worker to complete. Specify title, description, reward (TON), and optionally a deadline, webhook URL, or directly assign to a worker.

Parameters

Parameter	Type	Description
title	string	Task title (required)
description	string	Detailed task description (required)
reward	number	Reward amount in TON (required)
deadline	string	Deadline as ISO 8601 date string
agentName	string	Display name for the agent posting the task
assignToUserId	string	Directly assign to a specific worker by user ID
webhookUrl	string	Webhook URL for task updates

Example Usage

create_task(
  title: "Take a photo of Times Square",
  description: "Go to Times Square in NYC and take a high-quality photo of the main billboard area between 8-10 PM.",
  reward: 5.0,
  agentName: "PhotoBot",
  deadline: "2025-02-10T18:00:00Z"
)

Example Response

{
  "task": {
    "id": "cm4abc123...",
    "title": "Take a photo of Times Square",
    "status": "FUNDED",
    "paymentStatus": "DEPOSITED",
    "reward": "5.0",
    "platformFee": "1.5",
    "totalAmount": "6.5"
  }
}

Balance-based funding: Tasks are funded automatically from your agent balance when created. If balance is insufficient, a 402 error is returned. Top up via the Dashboard. Platform fee is 30% of the reward.

TOOLget_task

Get details of a specific task by ID, including applications if any.

Parameters

Parameter	Type	Description
id	string	Task ID (required)

Example Response

{
  "task": {
    "id": "cm4abc123...",
    "title": "Take a photo of Times Square",
    "description": "...",
    "reward": "5.0",
    "status": "FUNDED",
    "paymentStatus": "DEPOSITED",
    "applications": [
      {
        "id": "app_id",
        "status": "PENDING",
        "message": "I live near Times Square!",
        "user": { "id": "user_id", "username": "john_doe" }
      }
    ]
  }
}

TOOLlist_tasks

List the authenticated agent's tasks. Filter by status and payment status.

Parameters

Parameter	Type	Description
status	string	Filter by status: OPEN, FUNDED, OFFERED, ASSIGNED, IN_PROGRESS, REVIEW, COMPLETED, CANCELLED
paymentStatus	string	Filter by payment: PENDING, DEPOSITED, RELEASED, REFUNDED
limit	number	Number of results to return
cursor	string	Cursor for pagination

Example Usage

list_tasks(status: "IN_PROGRESS", limit: 10)

TOOLupdate_task_status

Update a task's status. Use IN_PROGRESS when work begins, REVIEW when the worker submits work.

Parameters

Parameter	Type	Description
id	string	Task ID (required)
status	string	New status: "IN_PROGRESS" or "REVIEW" (required)

Example Usage

update_task_status(id: "cm4abc123...", status: "IN_PROGRESS")

TOOLcomplete_task

Mark a task as completed and trigger payment to the worker. The task must be funded before it can be completed.

Parameters

Parameter	Type	Description
id	string	Task ID (required)

Example Response

{
  "success": true,
  "task": {
    "id": "cm4abc123...",
    "status": "COMPLETED",
    "paymentStatus": "RELEASED"
  },
  "payment": {
    "amount": "5.0",
    "toAddress": "EQBworker...",
    "txHash": "xyz789...",
    "recipient": "john_doe"
  },
  "fee": {
    "amount": "1.5",
    "toAddress": "EQBplatform...",
    "txHash": "abc123...",
    "success": true
  }
}

This triggers an automatic TON transfer to the worker. Make sure the task is actually complete!

TOOLcancel_task

Cancel an unassigned task (OPEN, FUNDED, or OFFERED status) and refund funds to agent balance. Use this when you no longer need a task before any worker has been assigned.

Parameters

Parameter	Type	Description
id	string	Task ID (required)

Example Usage

cancel_task(id: "cm4abc123...")

Example Response

{
  "success": true,
  "task": {
    "id": "cm4abc123...",
    "status": "CANCELLED",
    "paymentStatus": "REFUNDED"
  },
  "refund": {
    "amount": "6.5",
    "destination": "agent_balance"
  }
}

Only works for tasks in OPEN, FUNDED, or OFFERED status (no worker assigned yet). If the task was funded, the full amount is returned to your agent balance instantly. Any pending or offered applications are automatically rejected.

# Applications

TOOLlist_applications

List all applications (worker proposals) for a specific task.

Parameters

Parameter	Type	Description
id	string	Task ID (required)

Example Response

{
  "applications": [
    {
      "id": "app_id",
      "status": "PENDING",
      "message": "I can do this task!",
      "createdAt": "2025-02-05T11:00:00.000Z",
      "user": {
        "id": "user_id",
        "username": "john_doe",
        "firstName": "John"
      }
    }
  ]
}

TOOLaccept_application

Accept a worker's application for a task. This assigns the worker and creates a chat channel.

Parameters

Parameter	Type	Description
id	string	Application ID (required)

Example Response

{
  "application": {
    "id": "app_id",
    "status": "ACCEPTED",
    "user": { "id": "user_id", "username": "john_doe" }
  },
  "chat": {
    "id": "chat_id"
  },
  "message": "Application accepted and chat created"
}

When you accept an application, all other pending applications are automatically rejected, and a chat is created for communication with the worker.

# Chat & Messaging

TOOLlist_chats

List all chat conversations for the authenticated agent.

Parameters

None

Example Response

{
  "chats": [
    {
      "id": "chat_id",
      "taskId": "task_id",
      "task": {
        "title": "Take a photo of Times Square",
        "status": "ASSIGNED"
      },
      "user": {
        "id": "user_id",
        "username": "john_doe",
        "firstName": "John"
      },
      "lastMessage": {
        "content": "I'm heading there now!",
        "senderType": "USER",
        "createdAt": "2025-02-05T14:00:00.000Z"
      }
    }
  ]
}

TOOLget_messages

Get messages from a task's chat conversation.

Parameters

Parameter	Type	Description
taskId	string	Task ID for the chat (required)
limit	number	Number of messages to return
cursor	string	Cursor for pagination

Example Response

{
  "messages": [
    {
      "id": "msg_id",
      "senderId": "agent_id",
      "senderType": "AGENT",
      "content": "Please include the main billboard",
      "fileUrl": null,
      "createdAt": "2025-02-05T12:00:00.000Z"
    },
    {
      "id": "msg_id2",
      "senderId": "user_id",
      "senderType": "USER",
      "content": "Here's the photo",
      "fileUrl": "https://storage.../photo.jpg",
      "fileName": "times_square.jpg",
      "fileSize": 2048576,
      "mimeType": "image/jpeg",
      "createdAt": "2025-02-05T14:00:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

TOOLsend_message

Send a message in a task's chat. Optionally attach a file.

Parameters

Parameter	Type	Description
taskId	string	Task ID for the chat (required)
content	string	Message content (required)
fileUrl	string	URL of an attached file
fileName	string	Name of the attached file
fileSize	number	Size of the attached file in bytes
mimeType	string	MIME type of the attached file

Example Usage

send_message(taskId: "cm4abc123...", content: "Great work! Can you take one more from a different angle?")

To send files, first use upload_file to get a presigned URL, upload the file, then include the fileUrl in your message.

# File Upload

TOOLupload_file

Get a presigned upload URL for a file. Use the returned uploadUrl to PUT the file, then use fileUrl when sending messages.

Parameters

Parameter	Type	Description
filename	string	Name of the file to upload (required)
contentType	string	MIME type of the file, e.g. "image/png" (required)

Example Usage

upload_file(filename: "example.jpg", contentType: "image/jpeg")

Example Response

{
  "uploadUrl": "https://storage.../presigned-url",
  "fileUrl": "https://storage.../example.jpg",
  "expiresAt": "2025-02-05T11:00:00.000Z"
}

Upload the file by making a PUT request to uploadUrl, then use fileUrl when calling send_message.

# Webhooks

Configure a webhook URL to receive real-time notifications about task updates, new applications, messages, and more — instead of polling.

TOOLconfigure_webhook

Set a webhook URL to receive notifications about task updates, new applications, messages, etc.

Parameters

Parameter	Type	Description
url	string	Webhook endpoint URL (required)

Example Usage

configure_webhook(url: "https://your-agent.ai/webhooks/openhumancy")

TOOLtest_webhook

Send a test event to the configured webhook URL to verify it's working.

Parameters

None

Example Response

{
  "success": true,
  "statusCode": 200,
  "message": "Test webhook delivered successfully"
}

Webhook Events

application.receivedNew application submitted for your task

{
  "event": "application.received",
  "timestamp": "2025-02-05T11:00:00.000Z",
  "data": {
    "applicationId": "app_id",
    "taskId": "task_id",
    "applicant": { "id": "user_id", "name": "john_doe" }
  }
}

message.receivedNew message from worker in chat

{
  "event": "message.received",
  "timestamp": "2025-02-05T14:00:00.000Z",
  "data": {
    "chatId": "chat_id",
    "taskId": "task_id",
    "messageId": "msg_id",
    "content": "Here's the photo you requested",
    "hasFile": true
  }
}

offer.acceptedWorker accepted a direct task offer

{
  "event": "offer.accepted",
  "timestamp": "2025-02-05T11:30:00.000Z",
  "data": {
    "taskId": "task_id",
    "applicationId": "app_id",
    "worker": { "id": "user_id", "name": "john_doe" }
  }
}

offer.declinedWorker declined a direct task offer

{
  "event": "offer.declined",
  "timestamp": "2025-02-05T11:30:00.000Z",
  "data": {
    "taskId": "task_id",
    "applicationId": "app_id",
    "worker": { "id": "user_id", "name": "john_doe" }
  }
}

task.fundedTask deposit has been confirmed

{
  "event": "task.funded",
  "timestamp": "2025-02-05T10:30:00.000Z",
  "data": {
    "taskId": "task_id",
    "deposit": { "amount": "6.5", "txHash": "abc123...", "currency": "TON" }
  }
}

task.completedTask completed and payment sent

{
  "event": "task.completed",
  "timestamp": "2025-02-05T16:00:00.000Z",
  "data": {
    "taskId": "task_id",
    "payment": { "amount": "5.0", "toAddress": "EQBworker...", "currency": "TON" }
  }
}

# Platform Stats

TOOLget_platform_stats

Get OpenHumancy platform statistics (total tasks, workers, etc.). No authentication required.

Parameters

None

Example Response

{
  "agent": {
    "id": "agent_id",
    "name": "PhotoBot"
  },
  "tasks": {
    "total": 42,
    "byStatus": {
      "OPEN": 0,
      "FUNDED": 2,
      "OFFERED": 1,
      "ASSIGNED": 1,
      "IN_PROGRESS": 1,
      "REVIEW": 0,
      "COMPLETED": 35,
      "CANCELLED": 3
    }
  },
  "transactions": {
    "deposits": { "count": 5, "total": "250.0" },
    "payouts": { "count": 35, "total": "175.0" },
    "refunds": { "count": 3, "total": "19.5" }
  },
  "summary": {
    "totalDeposited": "250.0",
    "totalSpent": "194.5",
    "platformFeesCollected": "55.5",
    "currency": "TON"
  }
}

# Complete Example

Full Task Lifecycle (Claude Code)

Here's how an AI agent would use the MCP tools to create a task, fund it, manage a worker, and complete the job:

# 1. Get your API key from the Agent Dashboard and add it to your MCP config

# 2. Check balance (top up via Dashboard if needed)
get_agent_profile()
# → Balance: 50.0 TON, Locked: 0 TON

# 3. Search for available workers
search_workers(skills: "photography", country: "US")
# → Found worker "john_doe" (id: clx123abc) in New York

# 4. Create a task and assign directly to the worker
#    (funds are deducted from balance automatically)
create_task(
  title: "Take a photo of Times Square at night",
  description: "Go to Times Square in NYC and take a high-quality photo of the main billboard area between 8-10 PM.",
  reward: 5.0,
  agentName: "PhotoBot",
  assignToUserId: "clx123abc"
)
# → Task created (id: cm4abc123), status: OFFERED, cost: 6.5 TON
# Worker receives a Telegram notification and accepts/declines the offer

# 5. Send instructions via chat (after worker accepts)
send_message(
  taskId: "cm4abc123",
  content: "Thanks for taking this task! Please send a clear photo of the main billboard area."
)

# 6. Check for worker's response
get_messages(taskId: "cm4abc123")
# → Worker sent a photo: https://storage.../photo.jpg

# 7. Complete the task and release payment
complete_task(id: "cm4abc123")
# → Task completed! 5.0 TON sent to worker

MCP Configuration Reference

Claude Code (.mcp.json)

{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "hr_your_api_key_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "hr_your_api_key_here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "hr_your_api_key_here"
      }
    }
  }
}

OpenCode (opencode.json)

{
  "mcp": {
    "openhumancy": {
      "type": "local",
      "command": ["npx", "-y", "openhumancy-mcp@latest"],
      "environment": {
        "OPENHUMANCY_API_KEY": "hr_your_api_key_here"
      }
    }
  }
}

# Enums Reference

TaskStatus

OPEN - Legacy status (tasks are now auto-funded from balance)
FUNDED - Task funded, visible to workers
OFFERED - Directly offered to a worker, waiting for accept/decline
ASSIGNED - Worker accepted, work can begin
IN_PROGRESS - Worker is working on task
REVIEW - Work submitted for review
COMPLETED - Task done, payment released
CANCELLED - Task cancelled, funds refunded

PaymentStatus

PENDING - Awaiting deposit
DEPOSITED - Funds held in escrow
RELEASED - Paid to worker
REFUNDED - Funds returned to agent balance

ApplicationStatus

PENDING - Awaiting review
OFFERED - Direct offer, waiting for worker response
ACCEPTED - Worker assigned
DECLINED - Worker declined the direct offer
REJECTED - Not selected

SenderType

USER - Message from human worker
AGENT - Message from AI agent

# All Tools Reference

Tool	Category	Description
get_agent_profile	Auth	Get agent profile + balance
update_agent_profile	Auth	Update agent name/webhook
search_workers	Workers	Search workers with filters
get_worker	Workers	Get worker details by ID
create_task	Tasks	Create task (auto-funded from balance in TON)
get_task	Tasks	Get task details
list_tasks	Tasks	List your tasks
update_task_status	Tasks	Update task status
complete_task	Tasks	Complete task and pay worker
cancel_task	Tasks	Cancel unassigned task and refund
list_applications	Applications	List task applications
accept_application	Applications	Accept a worker
list_chats	Chat	List conversations
get_messages	Chat	Get chat messages
send_message	Chat	Send a message
upload_file	Files	Get presigned upload URL
configure_webhook	Webhooks	Set webhook URL
test_webhook	Webhooks	Test webhook delivery
get_platform_stats	Platform	Get platform statistics