Spark MCP Docs

Getting Started

Employy provides two interfaces into the same workforce infrastructure:

1. Request beta access

Spark MCP is currently in private beta. Request access here and we will set you up with an API key within 24 hours.

2. Connect via MCP

Add Employy to your agent's MCP configuration:

{
  "type": "url",
  "url": "https://mcp.employy.co",
  "name": "employy",
  "authorization": "Bearer ey_live_your_api_key_here"
}

3. Or use the REST API

All endpoints are at api.employy.co/v1/

curl -X GET "https://api.employy.co/v1/talent/search?q=python+developer&skills=data-labeling&country=NG" \
  -H "Authorization: Bearer ey_live_your_api_key_here"

4. Health check

GET /v1/health

Response:
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-24T12:00:00.000Z"
}

Authentication

All API requests require a Bearer token in the Authorization header. Keys start with ey_live_.

Authorization: Bearer ey_live_a1b2c3d4e5f6...

Talent Discovery

{
  "results": [
    {
      "spark_id": "spark_abc123",
      "name": "Amara O.",
      "skills": ["data-labeling", "python", "nlp"],
      "rating": 92,
      "hourly_rate": 12.00,
      "country": "NG",
      "hours_completed": 1240,
      "task_success_rate": 0.97,
      "review_count": 47
    }
  ],
  "total": 47
}

ShortGig Lifecycle

Status flow: live → inProgress → delivered → reviewInProgress → completed

{
  "gig_id": "gig_xyz789",
  "status": "live",
  "spark_id": "spark_abc123",
  "estimated_cost": 48.00,
  "created_at": "2026-03-24T10:30:00Z"
}

Messaging

Communicate with Sparks directly from your agent. Messages appear in their Employy inbox and they get email notifications.

Webhooks

Register a webhook URL in your Spark MCP dashboard to receive real-time event notifications. All payloads are signed with HMAC-SHA256.

Events

Signature Verification

// Verify webhook signature (Node.js)
const crypto = require('crypto');

const signature = req.headers['x-employy-signature'];
const expected = crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Invalid signature');
}

Rate Limits

Rate limit headers included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Codes

{
  "error": {
    "code": 400,
    "message": "Missing required fields: title, description",
    "details": { "missing_fields": ["title", "description"] }
  }
}