DEV Community

Cover image for Building a Custom MCP Server for Resolve.ai Clocked Fill, Extract and Decide
Ranjan Dailata
Ranjan Dailata

Posted on Edited on

Building a Custom MCP Server for Resolve.ai Clocked Fill, Extract and Decide

#mcp #automation #opensource #ai

Clocked MCP Client Extract Demo

Clocked MCP Client Extract Input

Clocked MCP Client Extract

Source Code

Download Source Code
Download Clocked MCP Client Extract Demo

Introduction

In this post, you will be guided on building a custom Model Context Protocol (MCP) server that exposes the Clocked Fill, Extract and Decide APIs from Rezolve.ai. The result is clocked-mcp-server - A standalone TypeScript app that translates MCP tool calls into HTTP requests to the Clocked Fill, Extract or Decide endpoint, making it easy to integrate AI-powered fill, extraction and decision-making into n8n workflows and other MCP-compatible clients.

Whether you're building an internal tool or looking to integrate AI extraction or decision making into your automation platform, this guide covers the architecture, implementation details, and practical usage patterns.

What is Clocked Fill?

Clocked Fill is a Rezolve.ai API that takes free-form text and structured field definitions, then uses AI to extract or score values based on those definitions. A typical request:

POST https://clocked.rezolve.ai/clocked/fill
{
  "text": "Server crashed during peak load yesterday",
  "fields": {
    "incident_id": { "type": "extract", "description": "The incident or ticket identifier" },
    "severity": { "type": "score", "levels": ["Low", "Medium", "High", "Critical"] }
  },
  "instructions": "Extract the ticket ID and assess urgency"
}
Enter fullscreen mode Exit fullscreen mode

The response returns extracted/scored values, enabling structured data capture from unstructured text.

What is Clocked Extract?

Clocked Extract is a Rezolve.ai API that takes free-form text and structured field definitions, then uses AI to extract specific entities or values based on those definitions. A typical request:

POST https://clocked.rezolve.ai/clocked/extract
{
  "text": "John Doe submitted a feature request for the payment integration",
  "fields": {
    "requester_name": { "type": "extract", "description": "The name of the person making the request" },
    "product_area": { "type": "extract", "description": "The product area being requested" }
  },
  "instructions": "Extract the requester name and product area"
}
Enter fullscreen mode Exit fullscreen mode

The response returns extracted entities, enabling structured data capture from unstructured text.

What is Clocked Decide?

Clocked Decide is a Rezolve.ai API that takes a state description (free-form text), optional shared instructions, and a set of decision questions, then uses AI to return an answer for each question. A typical request:

POST https://clocked.rezolve.ai/clocked/decide
{
  "state": "Server crashed during peak load yesterday",
  "instructions": "Assess the incident and recommend next steps",
  "questions": {
    "severity": { "type": "score", "levels": ["Low", "Medium", "High", "Critical"] },
    "needs_war_room": { "type": "choice", "options": ["Yes", "No"] },
    "affected_systems": { "type": "multiselect", "options": ["API", "Database", "Frontend"] }
  }
}
Enter fullscreen mode Exit fullscreen mode

The response returns a decision per question, enabling structured decision-making from unstructured state. Via the MCP server the state is supplied as the text argument, which the server maps to the Clocked Decide state field.

Why an MCP Server?

The Model Context Protocol is an open standard for AI tool exposure and discovery. Implementing an MCP server gives us:

  • Standardized tool invocation - Any MCP-compatible client (n8n, Claude Desktop, Cursor, etc.) can discover and call our tools
  • Streamable HTTP transport - Bi-directional communication over a single HTTP endpoint
  • Built-in authentication - MCP access tokens provide per-connection auth separate from API keys
  • Stateless operation - No server-side session management required

The clocked-mcp-server implements three tools: clocked_fill, clocked_extract and clocked_decide, which wrap the respective Clocked APIs inside the MCP framework.

Architecture Overview

HighLevel Architecture

The server is a TypeScript + Express application with ~7 source files. Here's the layer breakdown:

Layer File Responsibility
Configuration src/config.ts Environment variable loading, validation, defaults
Client src/clocked-extract-client.ts Low-level HTTP client for Clocked Extract API, timeout handling, error wrapping
Client src/clocked-fill-client.ts Low-level HTTP client for Clocked Fill API, timeout handling, error wrapping
Client src/clocked-decide-client.ts Low-level HTTP client for Clocked Decide API, timeout handling, error wrapping
Tool Schema src/tools/fill.ts Zod input validation for the clocked_fill tool
Tool Schema src/tools/extract.ts Zod input validation for the clocked_extract tool
Tool Schema src/tools/decide.ts Zod input validation for the clocked_decide tool
Middleware src/middleware.ts Auth validation, request ID extraction, idempotency handling
Routes src/index.ts MCP request handling, tool dispatch, health check

Clocked Fill Tool

The clocked_fill tool wraps the Clocked Fill API for n8n and other MCP clients. It accepts:

  • text (required): The free-form text to extract/scoring from
  • fields (required): Structured field definitions for the AI to extract/scoring values
  • instructions (optional): Additional instructions for the AI

The tool schema uses Zod for input validation, providing runtime validation and type safety.

Clocked Extract Tool

The clocked_extract tool wraps the Clocked Extract API for n8n and other MCP clients. It accepts:

  • text (required): The free-form text to extract entities from
  • fields (required): Structured field definitions for the AI to extract entities
  • instructions (optional): Additional instructions for the AI

The tool schema uses Zod for input validation, providing runtime validation and type safety.

Clocked Decide Tool

The clocked_decide tool wraps the Clocked Decide API for n8n and other MCP clients. It accepts:

  • text (required): The source state text to evaluate
  • questions (required): Decision questions defining the criteria. Each question declares a type (noul, choice, multiselect or score) and optional instructions, threshold, criteria and options
  • instructions (optional): Shared instructions for the decision process
  • request_id (optional): Idempotency key. Re-use the same UUID when retrying the same logical request

The tool schema uses Zod for input validation, providing runtime validation and type safety.

Using with n8n

To use the clocked-mcp-server with n8n, add the MCP tool node and configure:

  • Clocked Fill: Use the clocked_fill tool with appropriate text and field definitions
  • Clocked Extract: Use the clocked_extract tool with appropriate text and field definitions
  • Clocked Decide: Use the clocked_decide tool with state text and decision questions

The server runs on http://127.0.0.1:3001 by default, with authentication via MCP_ACCESS_TOKEN header.

Clocked MCP Server Documentation

The Clocked MCP Server on localhost could be access via the following URL. Assuming you have followed the instructions for setting up and running it on your local machine.

http://127.0.0.1:3001/docs/

Clocked MCP Server Documentation

Here's the Clocked Playground which you can use to get your hands dirty and learn the Clocked API usages.

Clocked MCP Server Playground

Clocked MCP Server Playground Run

Sample JSON response for the Clocked Fill

{
  "request_id": "1d227826-94b6-46f9-9280-ab1cbde29c91",
  "status": 200,
  "success": true,
  "result": {
    "model": "clocked-1.0",
    "fields": {
      "incident_id": {
        "value": "INC-8421",
        "start": 0,
        "end": 8,
        "confidence": 0.9999999991103827,
        "p_verify": 0.9999999991103827
      },
      "severity": {
        "value": "High",
        "confidence": 0.514,
        "expected": 3.03,
        "probabilities": {
          "Low": 0.07192893839681964,
          "Medium": 0.059605984870821235,
          "High": 0.6352049263591034,
          "Critical": 0.23326015037325568
        }
      },
      "affected_team": {
        "value": "payroll team",
        "start": 129,
        "end": 141,
        "confidence": 0.9999978503485066,
        "p_verify": 0.9999978503485066
      },
      "assigned_engineer": {
        "value": "Arjun Shah",
        "start": 347,
        "end": 357,
        "confidence": 0.9999999982234369,
        "p_verify": 0.9999999982234369
      },
      "workaround_available": {
        "value": "No",
        "confidence": 0.99,
        "probabilities": {
          "Yes": 0.005147460642875745,
          "No": 0.9948525393571243
        }
      }
    },
    "timing": {
      "read_ms": 120,
      "generate_ms": 0,
      "total_ms": 128,
      "source_states": 1,
      "source_prefills": 1,
      "shared_source_tokens": 352,
      "shared_read_generate_forwards": 0,
      "engine": "unified"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

CURL Cheat Sheet

Fill endpoint 

curl -X POST http://127.0.0.1:3001/api/fill \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Server crashed during peak load yesterday","fields":{"incident_id":{"type":"extract","description":"The incident ID"}},"instructions":"Extract the ticket ID and assess urgency"}'
Enter fullscreen mode Exit fullscreen mode

Extract endpoint 

curl -X POST http://127.0.0.1:3001/api/extract \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"John Doe submitted a feature request","fields":{"requester_name":{"type":"extract","description":"The requester name"}},"instructions":"Extract the requester name"}'
Enter fullscreen mode Exit fullscreen mode

Decide endpoint 

curl -X POST http://127.0.0.1:3001/api/decide \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Server crashed during peak load yesterday","questions":{"severity":{"type":"score","levels":["Low","Medium","High","Critical"]},"needs_war_room":{"type":"choice","options":["Yes","No"]}},"instructions":"Assess the incident and recommend next steps"}'
Enter fullscreen mode Exit fullscreen mode

Extract vs Fill

Area Insight
MCP SDK The @modelcontextprotocol/sdk handles most JSON-RPC framing, but StreamableHTTPServerTransport expects the SDK transport to own the response - avoid overriding res.json() or status codes in middleware.
Idempotency Providing a request_id enables Clocked's idempotency behavior. Re-use the same UUID when retrying the same logical request.
Statelessness The server does not maintain conversational state between calls. Each MCP request is independent, simplifying scaling but meaning you must carry all context in the request payload.
Auth separation MCP_ACCESS_TOKEN protects the MCP endpoint; CLOCKED_API_KEY is used only for outbound Clocked API calls. They are independent and can be managed separately.
Zod validation Using Zod for input schemas gives free runtime validation and type safety, but the schema must match what Clocked expects for the fields object - different workflows may need different field definitions.
Fill vs Extract vs Decide Clocked Fill extracts or scores values based on field definitions (often used for incident metadata), Clocked Extract extracts specific entities (often used for form-like data), and Clocked Decide returns answers to decision questions based on a state description. Choose the API that matches your use case.

Conclusion

Building an MCP server for the Clocked Fill, Extract and Decide APIs are about gluing together three well-established technologies: the MCP SDK (standard tool exposure), Express (flexible HTTP routing), and the Clocked AI API (intelligent text extraction, scoring and decision-making).

The resulting clocked-mcp-server is a lightweight, standalone TypeScript app that can be dropped into any Node.js environment, Docker container, or orchestrated deployment. Its primary value is enabling n8n users (and other MCP clients) to leverage AI-powered extract, fill and decide capabilities through a standardized interface, without needing to directly call the Clocked API or handle the JSON-RPC transport themselves.

If you're looking to add AI extraction or classification to your automation platform, this pattern - an MCP bridge between clients and a specialized AI API - can be replicated for other APIs too. For more information, please refer to Clocked Docs

Top comments (0)