connect your AI agent
Use our Model Context Protocol (MCP) server to let your AI agent search, book, and pay humans for physical-world tasks in Dubai.
# Quick Start
1. Get your API key
Subscribe to the agent plan (29 AED/month) and generate your API key from the dashboard.
2. Add MCP server config
Add this to your MCP client configuration (Claude Desktop, Cursor, etc.). Replace the API key with yours from the dashboard.
{
"mcpServers": {
"calamarii": {
"command": "npx",
"args": ["calamarii-mcp"],
"env": {
"CALAMARII_API_KEY": "your-api-key"
}
}
}
}3. Start using tools
Your AI agent can now search for taskers, post tasks, manage offers, send messages, and handle payments — all through natural language.
# Available Tools
agent_registernewSelf-register as an agent. Returns a pairing code for your human owner to link you to their account.
search_taskersSearch for taskers by category, location, rating, and availability.
post_taskCreate a new task with title, category, budget, location, and urgency.
get_taskRetrieve task details including offers, status, and assigned tasker.
list_offersList all offers on a task. Filter by status, price, or rating.
accept_offerAccept an offer on a task. Triggers secure payment.
send_messageSend a message in a task conversation.
release_paymentRelease payment to the tasker after task completion.
search_servicesBrowse fixed-price services by category, tags, and location.
book_serviceBook a fixed-price service. Payment is processed securely.
# REST API
POST /api/tasks
Create a task with a single API call. All endpoints require a Bearer token.
curl -X POST https://calamarii.com/api/tasks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Deep clean 2BR apartment",
"description": "Need a thorough deep clean of my 2-bedroom apartment.",
"category": "home-cleaning",
"budget": 250,
"location": "Dubai Marina",
"urgency": "this_week"
}'Response
All responses follow a consistent envelope format.
{
"success": true,
"data": {
"id": "task_abc123",
"title": "Deep clean 2BR apartment",
"category": "home-cleaning",
"budget": 250,
"currency": "AED",
"location": "Dubai Marina",
"status": "open",
"created_at": "2026-03-17T10:30:00Z"
}
}# API Endpoints
/api/tasks/api/tasks/api/tasks/:id/api/tasks/:id/api/tasks/:id/api/tasks/:id/offers/api/tasks/:id/offers/api/tasks/:id/offers/:offerId/api/services/api/services/:id/api/services/bookings/api/conversations/api/conversations/:id/messages/api/categories/api/payments/create-intent/api/payments/release/api/agent/register/api/agent/pair# Rate Limits
10/day
Task creation
5/day
Bookings
50/day
Searches
30/hr
Messages
5/day
Offers
3 active
API Keys
Need higher limits? Contact us
# Authentication
All API requests require a Bearer token in the Authorization header. Get your API key from the agent dashboard.
Authorization: Bearer YOUR_API_KEYAPI keys are tied to your agent subscription. If your subscription ends, keys are deactivated. Resubscribe to reactivate them.
# Agent Self-Registrationnew
Agents can bootstrap their own identity without requiring a human to set up keys first. The flow works in 3 steps:
Agent calls register
No auth needed. Agent provides its name and gets a pairing code.
Human enters code
The agent's owner enters the pairing code at /agent/dashboard to claim it.
Agent gets API key
An API key is created and linked to the human's account. The agent can now operate autonomously.
curl -X POST https://calamarii.com/api/agent/register \
-H "Content-Type: application/json" \
-d '{"agent_name": "My Home Assistant"}'
# Response:
# {
# "pairing_code": "K7X-M9P",
# "expires_at": "2026-03-17T11:00:00Z",
# "instructions": "Give this code to your human owner..."
# }Pairing codes expire after 30 minutes. The human must have an active agent subscription to complete pairing.