KirokuForms MCP Server

Quick Start

1. Prerequisites

• A KirokuForms account and API key with hitl:create, hitl:read, and forms:write scopes.
• A compatible MCP client (e.g., Cursor) or an API tool like curl.

2. Server Information

3. Test Your Connection

A GET returns the server's capabilities, which is a quick way to confirm your API key works:

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.kirokuforms.com/api/mcp

To drive the MCP protocol itself, POST a JSON-RPC initialize request. This is the same handshake an MCP client runs on connect; the reply carries the protocolVersion and serverInfo. The Accept header must list both application/json and text/event-stream.

curl -X POST https://www.kirokuforms.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

4. Plans and limits

Every plan can call the MCP server, including the free one, and an API key needs no subscription. What changes with the plan is how many requests a minute we accept before answering 429.

Moving up a plan raises that number. The pricing page shows what each plan costs.

A refusal carries Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers, so a client knows how long to wait before it tries again. The count is kept per API key against a fixed clock minute, so it resets on the minute rather than sixty seconds after your first call.

Every plan can also set how long a review stays open: pass settings.expiration when you create the task. A task nobody sets a deadline for expires after 72 hours, and whoever opened it is told it went unanswered, so a paused workflow hears back either way.

Client Configuration

The server is remote and speaks the Streamable HTTP transport at https://www.kirokuforms.com/api/mcp. Cursor and VS Code connect to that URL directly. Claude Desktop speaks stdio only, so it reaches the endpoint through the mcp-remote bridge, which forwards your Bearer key on every request.

{
  "mcpServers": {
    "kirokuforms": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://www.kirokuforms.com/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "kirokuforms": {
      "url": "https://www.kirokuforms.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "kirokuforms": {
      "type": "http",
      "url": "https://www.kirokuforms.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available Tools

A tools/list call advertises three HITL tools that tools/call can invoke: request-human-review (create a task), list-hitl-tasks (list the tasks this key created), and cancel-hitl-task (cancel a pending task and revoke its links). Each tool is also reachable as a REST endpoint for clients that do not speak MCP.

Available Resources

Resources are entities you can retrieve information about via GET requests.

Python SDK Example

The easiest way to integrate is with our Python SDK, which handles API requests, dynamic form generation, and polling.

# Install the Python SDK. Full reference: https://chelseaaiventures.github.io/langgraph-kirokuforms/
pip install git+https://github.com/ChelseaAIVentures/langgraph-kirokuforms.git

# Basic usage
from kirokuforms import KirokuFormsHITL
import time

client = KirokuFormsHITL(api_key="your_api_key_here")

# 1. Create a verification task using dynamic form generation
print("Creating HITL task...")
task_response = client.create_verification_task(
    title="Verify New Customer Data",
    description="Please review the information for Acme Corp and confirm its accuracy.",
    data={"company_name": "Acme Corp", "revenue": 1500000, "is_active": True}
)

task_id = task_response.get('taskId')
review_url = task_response.get('reviewUrl')

print(f"Task created with ID: {task_id}")
print(f"Please complete the review at: {review_url}")
print("\nWaiting for task completion (polling every 5s)...")

# 2. Poll for the result
try:
    # The get_task_result method handles the polling logic
    final_result = client.get_task_result(task_id, timeout=300) # 5 minute timeout
    
    print("\n✅ Task Completed!")
    print("Human Response:")
    print(final_result)

except TimeoutError as e:
    print(f"\n❌ {e}")

Webhook & Event Integration

For real-time updates, you can use webhooks or subscribe to Server-Sent Events (SSE).

Webhook Callbacks

If you provide a callbackUrl when creating a task, KirokuForms will send a POST request to that URL upon completion.

POST /your-callback-url

{
  "eventType": "hitl.task.completed",
  "taskId": "task-abc123",
  "timestamp": "2025-01-15T15:30:00Z",
  "data": {
    "status": "completed",
    "formData": {
      "customer_name": "Acme Corporation",
      "is_verified": "yes",
      "comments": "Updated company name based on latest filing."
    }
  }
}

Event Streaming (SSE)

For clients that can maintain a connection, you can subscribe to real-time events.

GET /api/mcp/events/hitl.task.completed
Authorization: Bearer YOUR_API_KEY