KirokuForms MCP Server

A Model Context Protocol (MCP) server providing Human-in-the-Loop (HITL) capabilities, dynamic form generation, and intelligent data collection for AI systems. Seamlessly integrate human oversight into your AI workflows with standardized MCP tools.

What is Model Context Protocol?

MCP is an open protocol that enables AI models to securely interact with local and remote resources through standardized server implementations. KirokuForms implements MCP to provide:

Structured human-in-the-loop capabilities for AI workflows
Dynamic form generation based on context and data analysis
Real-time event streaming for task completion notifications
Standardized APIs that work with all MCP-compatible clients

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

Server Name:
KirokuForms MCP Server v1.0.0

Base URL:
https://www.kirokuforms.com/api/mcp

Authentication:
Authorization: Bearer YOUR_API_KEY

3. Test Your Connection

Run the following command to verify your API key and connection. It should return a JSON object with the server's capabilities.

Check Server Capabilities

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

Client Configuration

Configure your preferred MCP client to use the KirokuForms server.

In Claude Desktop settings, go to the "Developer" tab and add the following to your configuration:

Claude Desktop Configuration

{
  "mcpServers": {
    "kirokuforms": {
      "command": "npx",
      "args": ["-y", "@kirokuforms/mcp-server"],
      "env": {
        "KIROKU_API_KEY": "your_api_key_here"
      }
    }
  }
}

In your project, create a file at .cursor/mcp.json with the following content:

.cursor/mcp.json

{
  "mcpServers": {
    "kirokuforms": {
      "command": "npx",
      "args": ["-y", "@kirokuforms/mcp-server"],
      "env": {
        "KIROKU_API_KEY": "your_api_key_here"
      }
    }
  }
}

In your project, create a file at .vscode/mcp.json with the following content:

.vscode/mcp.json

{
  "servers": {
    "kirokuforms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kirokuforms/mcp-server"],
      "env": {
        "KIROKU_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace Your API Key

Make sure to replace your_api_key_here with your actual API key from the KirokuForms Developer Dashboard.

Available Tools

The server exposes tools that an AI model can call to perform actions.

request-human-review

Creates a Human-in-the-Loop (HITL) task that pauses an AI workflow, generates a web form, and waits for human input.

Endpoint: POST /api/mcp/tools/request-human-review

Key Features:

Dynamic Form Generation: If you only provide inputData, the server analyzes it and generates appropriate form fields (e.g., text, number, radio buttons for booleans).
Template-Based Forms: Use a pre-configured KirokuForms template by providing a templateId.
Custom Field Definitions: Define the exact form fields, validation rules, and layout using a formDefinition object.

Core Parameters:

inputData: (Optional) A JSON object with initial data to pre-fill the form or for dynamic generation.

formDefinition: (Optional) A JSON object defining the form's fields and structure.

templateId: (Optional) The ID of an existing KirokuForms template to use.

callbackUrl: (Optional) A webhook URL to be called upon task completion.

expiresInSeconds: (Optional) A timeout in seconds for the task.

Returns:

taskId: The unique identifier for the created task.
reviewUrl: The direct URL for the human reviewer to complete the task.
status: The initial status of the task (e.g., pending).

Available Resources

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

`hitl/tasks/{taskId}`

Retrieve a HITL task's status, progress, and final results. This is essential for polling for task completion if you are not using webhooks.

`forms`

Access form definitions, templates, and aggregated submission data. (Full API documentation forthcoming).

`submissions`

Access ggregated submission data. (Full API documentation forthcoming).

Python SDK Example

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

Full Workflow with Python SDK

# Install the Python SDK
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.

Example Webhook Payload

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.

Subscribe to Task Completion Events

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

Get Started Quickly