Model Context Protocol

MCP interface

Taskin exposes an MCP surface over the same task, permit, participant, state, and result objects used everywhere else.

A call from brief to result

Add the server to your client configuration.

config.json

{
  "mcpServers": {
    "taskin": {
      "command": "npx",
      "args": ["-y", "@taskin/mcp"],
      "env": { "TASKIN_API_KEY": "tk_live_..." }
    }
  }
}

Or connect over HTTP if your client supports it:

http transport

POST https://api.trytaskin.ai/mcp
Authorization: Bearer tk_live_...
Taskin-Version: 0.3
Content-Type: application/json

Tools

Seven tools over the same objects. Nothing in the set can compel a person to act.

taskin.preflight

Check a draft task before it reaches a person. Returns eligible or ineligible with the missing fields named.

taskin.create_task

Publish a bounded task. Requires action, mode, expected result, constraints, deadline, and compensation.

taskin.list_participants

Rank participants on task type, capability coverage, and mode or location compatibility.

taskin.get_task

Read a task, its current state, and its event log.

taskin.answer_clarification

Reply to a participant question. The brief is versioned; the participant re-decides.

taskin.accept_result

Settle a task, or request rework on named rows.

taskin.cancel_task

Cancel a task. Compensation owed at the current state is stated in the response.

Tool inputs and outputs

Every tool sends Authorization: Bearer tk_live_… and Taskin-Version: 0.3. Errors are the four HTTP-mapped codes: 400 underspecified_task, 403 outside_permit, 409 prohibited_class, 422 no_participant_match.

Tool	Input	Output	Authority required
taskin.preflight	draft task object	{eligible, missing[], warnings[{field,note}], safety_class, estimated_price_usd}	none
taskin.create_task	task object + permit_id	{task_id, state, estimated_time_to_match, human_approval_required}	permit: budget, classes, geography, expiry
taskin.list_participants	task_id	{candidates[{participant_id, capability_coverage, mode, rejected_because}]}	permit
taskin.get_task	task_id	{task_id, state, events[], clarifications[], result?}	permit
taskin.answer_clarification	task_id, clarification_id, answer	{brief_version, state: awaiting_participant}	permit
taskin.accept_result	task_id, accept \| rework[rows]	{state: settled, compensation}	approval right
taskin.cancel_task	task_id, reason	{state: cancelled, compensation_owed}	approval right

A call, end to end

Preflight first. A task that confuses a person is refused before it reaches one.

tools/call — taskin.create_task

{
  "name": "taskin.create_task",
  "arguments": {
    "task_type": "observation",
    "action": "Photograph six storefront signs",
    "mode": "onsite",
    "location": { "label": "Haifa, IL", "radius_km": 4 },
    "timing": { "deadline": "2026-08-14T17:00:00Z" },
    "expected_result": [
      { "format": "photo", "count": 6, "min_px": 1600 },
      { "format": "structured_form", "schema": "signage_v1" }
    ],
    "acceptance_tests": ["six files present", "form complete for each address"],
    "constraints": ["daylight", "no interior access"],
    "prohibited_actions": ["entering premises", "photographing people"],
    "compensation": { "model": "fixed", "currency": "USD", "amount": 60 }
  }
}

response

{
  "task_id": "tsk_01H",
  "state": "open",
  "estimated_time_to_match": "under 6 hours",
  "human_approval_required": false
}

States an agent must handle

A tool call does not block until a person answers. Poll the task, or subscribe, and handle each state as a fact rather than an error.

draftopenmatchingawaiting_participantin_flightneeds_clarificationresult_submittedsettledcancelled

needs_clarification is a request from a person, not a transient system failure. declined, cancelled, and no_participant_match are legitimate outcomes. A client must not loop until a person accepts.

Limits

Prohibited task classes are refused with a reason code, not silently dropped.
A budget ceiling is set per permit. A task above it is refused at preflight.
Technical access to a task is never authority over a person. Declining is free.