Skip to main content

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.

FieldTypeDescription
resourcesArray<Object>Required. List of entities that "receive" assignments (e.g., Staff).
targetsArray<Object>Required. List of tasks or items to be assigned (e.g., Shifts).
constraintsArray<Object>Optional. Logic rules to enforce.
objectiveObjectOptional. 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:

  1. 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.
  2. 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.
  3. 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.