CLAIM

npx add-mcp 'https://claim.aiagenthuddle.com/mcp'

What it does

Acquire an exclusive lease or a capacity-limited semaphore, renew before expiry and release when finished. Increasing fencing tokens help cooperating consumers reject stale workers.

Public developer beta: documentation, signup and free usage are available. Use your product API key for requests; public examples do not require Vercel preview access. Paid subscriptions are available; free usage remains available.

Start here: one working example

1. Create an account, confirm your email, then create your CLAIM project. Free access is enough; no subscription is needed for this example.
2. Save the API key while it is visible. Keep it in server-side configuration.
3. Use Node.js 22 or newer. Download the standalone example and create a private .env file alongside it.

CLAIM_API_KEY=replace_with_your_project_key

Add .env to .gitignore. Never commit it, put it in a browser bundle or paste credentials into support messages.

node --env-file=.env claim-contention.mjs

What success looks like

The script checks GRANTED → DENIED while a lease is held, then RELEASED → GRANTED with a higher fencing token. It releases all known grants in a finally block. This is a single-process demonstration, not evidence of independent agents or protection of a real downstream write.

Expected output includes PASS:. Read the accompanying state messages too: workers and downstream storage must enforce ownership and fencing. The example makes real API requests and uses a small number of your request units.

Something failed? Check the setup table below before changing a key or repeating an uncertain action.

REST endpoints

Endpoint	Behaviour
POST /v1/leases	Acquire ownership. HTTP 200 GRANTED or 409 DENIED.
POST /v1/leases/{id}/renew	Renew an unexpired lease; expired authority cannot return.
DELETE /v1/leases/{id}	Release an active lease. NOT_ACTIVE is a safe terminal result.
GET /v1/resources/{resource}/status	Observe capacity and availability within your project.
POST /v1/resources/{resource}/wait	Wait for availability, bounded to at most 20 seconds. Acquisition remains competitive.

Failure behaviour and limits

• Fencing tokens are decimal strings. Compare them as integers and enforce them in the downstream system that commits the effect. A lease cannot stop an expired worker by itself.
• Use a stable request_id when retrying the same acquire, renew or release request. Without it, another acquire is a new operation. A replay cannot revive an expired lease.
• Successful release receipts replay their original result. A fresh release returning NOT_ACTIVE does not store or reserve its request ID, so different input using that unrecorded ID can be treated as a new request. Use distinct IDs for distinct requests. Stored receipts reject different-input reuse.
• Resources are isolated by project. Default mode is exclusive; semaphore mode requires an explicit capacity.
• The hosted preview passed one 1,000-request exclusive burst and one capacity-five burst after connection-limit failures were repaired. This is correctness evidence under those conditions, not an unlimited-throughput SLA.

Request bodies are limited to 16 KiB. Missing, revoked or cross-product keys are rejected. Rate limits return HTTP 429; service unavailability remains an error rather than a successful operation.

Runnable examples and integration checklist

Download claim-contention.mjs · Read the public example source. No npm dependency or paid plan is required.

When this tool helps

Use CLAIM when independently running workers need shared temporary ownership or a bounded number of concurrent holders. If your existing database already provides suitable coordination, another service may be unnecessary. CLAIM exposes ownership through HTTP/MCP; safe downstream writes still require atomic fencing enforcement.

Before putting it in a worker

• Keep the same request ID when retrying one uncertain request; a different request needs a different ID.
• Renew before expiry, stop work when authority is lost and release in cleanup.
• Compare fencing tokens as integers. Compare and commit atomically in the downstream storage system; an in-memory check is insufficient.
• Handle HTTP 429 and temporary failures with bounded backoff. Do not turn retries into an unbounded loop.

Setup problems

What you see	What to check
HTTP 401	Use this product's project API key in Authorization: Bearer. A Supabase key, Stripe key or the other product's key will not authenticate. Replaced keys stop working immediately.
HTTP 400	Check field names, types and required values against the example. TTL is an integer from 5 to 86,400 seconds; request IDs must be UUIDs.
HTTP 409	DENIED is normal contention: another holder owns capacity. Wait with bounded backoff; do not start work without GRANTED.
HTTP 429	Check monthly usage and rate limits. Wait before another attempt; never bypass a denial by starting work.
Timeout or interrupted example	Stop work. Unknown grants expire after the example’s 60-second TTL. In your integration retain request IDs to recover uncertain acquisitions.

For support, send the product name, a redacted error/status, operation or lease ID and UTC timestamp to accounts@aiagenthuddle.com. Never send API keys, provider tokens, passwords or sign-in links.

Engineering notes

An expired lease cannot stop a worker: a concrete failure scenario and the limits of the recovery mechanism.

MCP and SDK access

Connect an MCP client

Choose a remote server using Streamable HTTP. Use the following connection details in a client that supports bearer headers:

Server URL	https://claim.aiagenthuddle.com/mcp
Header	Authorization: Bearer YOUR_CLAIM_API_KEY
Expected tools	claim_acquire, claim_renew, claim_release, claim_status, claim_wait

Use your client's private credential configuration. A client that only supports OAuth cannot authenticate to this API-key endpoint. If discovery returns 401, check the header before invoking tools.

JavaScript · Node.js

Save the module as sdk.js in a project with "type": "module". The client uses the built-in fetch API.

import { ClaimClient } from './sdk.js';

const claim = new ClaimClient(
  'https://claim.aiagenthuddle.com',
  process.env.CLAIM_API_KEY
);

const result = await claim.acquire({
  resource: 'job/123', agent_id: 'worker-a',
  ttl_seconds: 30, request_id: crypto.randomUUID()
});
// Inspect GRANTED / DENIED before starting work.
// Enforce the granted fencing token downstream.
console.log(result);

Authenticated stateless MCP is available at /mcp. Tools: claim_acquire, claim_renew, claim_release, claim_status, claim_wait. Official current and legacy clients have passed protected hosted checks. No resumable SSE sessions or unsupported MCP features are advertised.

The standalone JavaScript client is available directly. Download sdk.js into your server-side project. No npm package is published. Keep credentials outside browser bundles.