API & MCP Integration

AutoAllocate is designed for automation and integration. Whether you are building a custom application or connecting AI agents (like Claude) to our engine, our technical interfaces provide the power you need.

Public Solver API

Programmatic access is available via our REST API. You can generate API keys in your Account Settings.

Endpoint

POST https://autoallocate.com/app/api/v1/solve

1. Request Header

You must include your API key as a Bearer token.

Authorization: Bearer sk_your_api_key_here
Content-Type: application/json

2. Request Body (JSON)

The engine expects three main arrays and an optional objective block.

Field	Type	Description
`resources`	Array<Object>	Required. List of entities that "receive" assignments (e.g., Staff).
`targets`	Array<Object>	Required. List of tasks or items to be assigned (e.g., Shifts).
`constraints`	Array<Object>	Optional. Logic rules to enforce.
`objective`	Object	Optional. Optimisation strategy (defaults to `MINIMIZE_UNASSIGNED`).

Resource Object

{
  "resourceId": "RES_1",         // Unique string ID
  "resourceCapacity": 40,        // Number: Max "weight" this resource can take
  "resourceAttributes": {        // Optional: Custom data for matching
    "skill": "senior",
    "location": "London",
    "availability": ["2026-06-01", "2026-06-02"] // Date attributes as flat arrays
  }
}

Target Object

{
  "targetId": "TAR_101",         // Unique string ID
  "targetSize": 8,               // Number: The "weight" this target consumes
  "targetAttributes": {          // Optional: Custom data for matching
    "required_skill": "senior",
    "city": "London",
    "date": ["2026-06-01"]
  }
}

3. Response Body (JSON)

Success (200 OK)

{
  "status": "OPTIMAL",           // Status: OPTIMAL, FEASIBLE, or INFEASIBLE
  "allocations": [
    {
      "resourceId": "RES_1",
      "assignedTargets": ["TAR_101", "TAR_105"],
      "utilization": {
        "capacityUsed": 15,
        "capacityRemaining": 25
      }
    }
  ],
  "metrics": {
    "solveTimeMs": 145.2,
    "targetsAssignedCount": 42,
    "totalUnassigned": 0
  },
  "creditsDeducted": 2,          // Number of credits spent
  "refunded": false
}

Error Responses

401 Unauthorized: Invalid or missing API key.
402 Payment Required: Insufficient credits to run this specific payload.
400 Bad Request: Invalid JSON or missing required fields (resources/targets).
502 Bad Gateway: The backend engine encountered a logic error or crashed (Credits are auto-refunded).

Model Context Protocol (MCP) Server

AutoAllocate implements a high-performance Model Context Protocol (MCP) server, enabling AI agents like Claude or Cursor to act as expert allocation assistants. This allows you to provide high-level natural language instructions and have the AI handle the complex JSON formatting and constraint mapping for you.

🚀 Quick Start

1. Generate a Token

Go to your Account Settings and select the MCP Agent tab. You can use either:

Per-User Token: Generated in the UI (recommended for personal use).
Master Token: Set via the MCP_TOKEN environment variable on your server.

2. Choose Your Endpoint

Global Endpoint: https://autoallocate.com/app/api/v1/mcp A general-purpose solver for any allocation problem.
Per-Project Endpoint: https://autoallocate.com/app/api/v1/mcp/[scenarioId] A specialised, context-aware endpoint. It provides the AI with your project's specific terminology and custom attributes. Enable this in your Project Dashboard > AI Agent tab.

3. Configure Your Client

Claude Desktop (mcp-remote bridge) Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "autoallocate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "ENDPOINT_URL",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Cursor / IDEs (Direct HTTP)

{
  "autoallocate": {
    "url": "ENDPOINT_URL",
    "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
  }
}

🛠️ Available Tools

1. `get_credit_balance`

Purpose: Allows the AI to check your current available funds.
Credit Cost: 0 Credits.

2. `get_solver_capabilities` (Global Mode Only)

Purpose: Engine logic discovery. Tells the AI exactly what mathematical constraints and objectives are supported to prevent "rule hallucination".
Returns: A JSON schema of all supported constraints (e.g. resource_max_capacity, date_range_overlap) and optimisation objectives.
Credit Cost: 0 Credits.

3. `validate_allocation`

Purpose: Dry-run validation of the AI's constructed payload.
Logic: Performs structural and type-checking against the project's specific schema (ID checks, numeric types, attribute mapping).
Credit Cost: 0 Credits.

4. `solve_allocation`

Purpose: Executes the full mathematical optimisation solver.
Billing Logic: Uses atomic "Reserve & Refund" logic. Credits are reserved before execution and automatically refunded if the problem is deemed INFEASIBLE or the engine encounters a backend error.
Credit Cost: 1 to 5 Credits (Calculated based on Matrix Score).

🎯 Advanced: Per-Project Context

The most powerful feature of the AutoAllocate MCP server is Scenario-Specific Intelligence. When using a Per-Project endpoint, the server dynamically rewrites the AI's manual:

Terminology Injection: The tool's input schema and descriptions use your Custom Labels. If you label resources as "Nurses", the AI sees {"Nurse": "string"} as a required field instead of resourceName.
Automated Rule Injection: AI agents do not need to understand or submit constraints in project mode. The server automatically merges your project's pre-configured rules and optimisation goals into every solve request.
Dynamic Attribute Schemas: The server generates precise nested schemas for attributes. It enforces types (e.g. Numeric fields) and instructs the AI to use YYYY-MM-DD arrays for all scheduling matches.

🛡️ Technical Brief & Integrity

Architecture

Transport: Custom in-process Promise-based bridge (Node.js-free, optimised for Cloudflare Workers / Edge).
Session Management: Stateful JSON-RPC 2.0 sessions managed via mcp-session-id headers to ensure reliable multi-step tool calls.
Security: SHA-256 hashed tokens stored in Cloudflare D1 with "Show Once" secret generation.

Safety Mechanisms

Collision Protection: The system prevents users from defining attributes that conflict with core engine keys (id, capacity, size) or project labels.
Svelte 5 Compatibility: Automatically "un-proxies" reactive state before database operations to ensure structuredClone compatibility.
Graceful Rejection: Explicitly returns 405 SSE Not Supported to prevent client hangs during transport fallback.

Public Solver API​

Endpoint​

1. Request Header​

2. Request Body (JSON)​

Resource Object​

Target Object​

3. Response Body (JSON)​

Success (200 OK)​

Error Responses​

Model Context Protocol (MCP) Server​

🚀 Quick Start​

1. Generate a Token​

2. Choose Your Endpoint​

3. Configure Your Client​

🛠️ Available Tools​

1. get_credit_balance​

2. get_solver_capabilities (Global Mode Only)​

3. validate_allocation​

4. solve_allocation​

🎯 Advanced: Per-Project Context​

🛡️ Technical Brief & Integrity​

Architecture​

Safety Mechanisms​