CLAIM

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

O que faz

Adquira uma concessão exclusiva ou um semáforo com capacidade limitada, renove antes da expiração e libere quando terminar. Tokens de fencing crescentes ajudam consumidores cooperativos a rejeitar workers obsoletos.

Beta pública para desenvolvedores: documentação, cadastro e uso gratuito estão disponíveis. Use sua chave de API do produto para requisições; exemplos públicos não exigem acesso de preview do Vercel. Assinaturas pagas estão disponíveis; o uso gratuito permanece disponível.

Comece aqui: um exemplo funcional

1. Crie uma conta, confirme seu e-mail e crie seu projeto CLAIM. O acesso gratuito é suficiente; nenhuma assinatura é necessária para este exemplo.
2. Salve a chave de API enquanto ela estiver visível. Mantenha-a na configuração do lado do servidor.
3. Use Node.js 22 ou mais recente. Baixe o exemplo autônomo e crie um arquivo privado .env ao lado dele.

CLAIM_API_KEY=replace_with_your_project_key

Adicione .env ao .gitignore. Nunca o envie para commits, coloque-o em um bundle de navegador ou cole credenciais em mensagens de suporte.

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

Como é o sucesso

O script verifica GRANTED → DENIED enquanto uma concessão está ativa, depois RELEASED → GRANTED com um token de fencing mais alto. Ele libera todas as concessões conhecidas em um bloco finally. Esta é uma demonstração de processo único, não uma evidência de agentes independentes ou proteção de uma gravação downstream real.

A saída esperada inclui PASS:. Leia também as mensagens de estado que o acompanham: workers e armazenamento downstream devem aplicar a propriedade e o fencing. O exemplo faz requisições reais à API e usa um pequeno número de suas unidades de requisição.

Algo falhou? Verifique a tabela de configuração abaixo antes de alterar uma chave ou repetir uma ação incerta.

Endpoints REST

Endpoint	Comportamento
POST /v1/leases	Adquire a propriedade. HTTP 200 GRANTED ou 409 DENIED.
POST /v1/leases/{id}/renew	Renova uma concessão não expirada; autoridade expirada não pode retornar.
DELETE /v1/leases/{id}	Libera uma concessão ativa. NOT_ACTIVE é um resultado terminal seguro.
GET /v1/resources/{resource}/status	Observa capacidade e disponibilidade dentro do seu projeto.
POST /v1/resources/{resource}/wait	Aguarda disponibilidade, limitado a no máximo 20 segundos. A aquisição permanece competitiva.

Comportamento de falhas e limites

• Tokens de fencing são strings decimais. Compare-os como inteiros e aplique-os no sistema downstream que confirma o efeito. Uma concessão não pode impedir um worker expirado por si só.
• Use um request_id estável ao repetir a mesma requisição de adquirir, renovar ou liberar. Sem ele, outra aquisição é uma nova operação. Uma repetição não pode reviver uma concessão expirada.
• Recibos de liberação bem-sucedidos repetem seu resultado original. Uma nova liberação que retorna NOT_ACTIVE não armazena nem reserva seu ID de requisição, portanto, uma entrada diferente usando esse ID não registrado pode ser tratada como uma nova requisição. Use IDs distintos para requisições distintas. Recibos armazenados rejeitam reutilização com entrada diferente.
• Os recursos são isolados por projeto. O modo padrão é exclusivo; o modo semáforo exige capacidade explícita.
• O preview hospedado passou em uma rajada exclusiva de 1.000 requisições e uma rajada de capacidade cinco após falhas de limite de conexão serem corrigidas. Isso é evidência de correção nessas condições, não um SLA de throughput ilimitado.

Os corpos das requisições são limitados a 16 KiB. Chaves ausentes, revogadas ou de produtos cruzados são rejeitadas. Limites de taxa retornam HTTP 429; indisponibilidade do serviço permanece um erro, não uma operação bem-sucedida.

Exemplos executáveis e checklist de integração

Baixe claim-contention.mjs · Leia o código-fonte do exemplo público. Nenhuma dependência npm ou plano pago é necessária.

Quando esta ferramenta ajuda

Use CLAIM quando workers executados de forma independente precisam de propriedade temporária compartilhada ou um número limitado de detentores simultâneos. Se seu banco de dados existente já fornece coordenação adequada, outro serviço pode ser desnecessário. CLAIM expõe a propriedade via HTTP/MCP; gravações downstream seguras ainda exigem aplicação atômica de fencing.

Antes de colocar em um worker

• Mantenha o mesmo ID de requisição ao repetir uma requisição incerta; uma requisição diferente precisa de um ID diferente.
• Renove antes da expiração, pare o trabalho quando a autoridade for perdida e libere na limpeza.
• Compare tokens de fencing como inteiros. Compare e confirme atomicamente no sistema de armazenamento downstream; uma verificação em memória é insuficiente.
• Trate HTTP 429 e falhas temporárias com backoff limitado. Não transforme repetições em um loop infinito.

Problemas de configuração

O que você vê	O que verificar
HTTP 401	Use a chave de API do projeto deste produto em Authorization: Bearer. Uma chave Supabase, chave Stripe ou a chave do outro produto não autenticará. Chaves substituídas param de funcionar imediatamente.
HTTP 400	Verifique nomes de campos, tipos e valores obrigatórios em relação ao exemplo. TTL é um inteiro de 5 a 86.400 segundos; IDs de requisição devem ser UUIDs.
HTTP 409	DENIED é contenção normal: outro detentor possui a capacidade. Aguarde com backoff limitado; não inicie o trabalho sem GRANTED.
HTTP 429	Verifique o uso mensal e os limites de taxa. Aguarde antes de outra tentativa; nunca contorne uma negação iniciando o trabalho.
Tempo esgotado ou exemplo interrompido	Pare o trabalho. Concessões desconhecidas expiram após o TTL de 60 segundos do exemplo. Na sua integração, retenha IDs de requisição para recuperar aquisições incertas.

Para suporte, envie o nome do produto, um erro/status editado, o ID da operação ou concessão e o timestamp UTC para accounts@aiagenthuddle.com. Nunca envie chaves de API, tokens de provedor, senhas ou links de login.

Notas de engenharia

Uma concessão expirada não pode impedir um worker: um cenário de falha concreto e os limites do mecanismo de recuperação.

Acesso MCP e SDK

Conecte um cliente MCP

Escolha um servidor remoto usando Streamable HTTP. Use os seguintes detalhes de conexão em um cliente que suporte cabeçalhos bearer:

URL do servidor	https://claim.aiagenthuddle.com/mcp
Cabeçalho	Authorization: Bearer YOUR_CLAIM_API_KEY
Ferramentas esperadas	claim_acquire, claim_renew, claim_release, claim_status, claim_wait

Use a configuração de credenciais privadas do seu cliente. Um cliente que só suporta OAuth não pode autenticar neste endpoint de chave de API. Se a descoberta retornar 401, verifique o cabeçalho antes de invocar as ferramentas.

JavaScript · Node.js

Salve o módulo como sdk.js em um projeto com "type": "module". O cliente usa a API fetch integrada.

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);

MCP autenticado sem estado está disponível em /mcp. Ferramentas: claim_acquire, claim_renew, claim_release, claim_status, claim_wait. Clientes oficiais atuais e legados passaram em verificações hospedadas protegidas. Nenhuma sessão SSE retomável ou recursos MCP não suportados são anunciados.

O cliente JavaScript autônomo está disponível diretamente. Baixe sdk.js no seu projeto do lado do servidor. Nenhum pacote npm é publicado. Mantenha credenciais fora de bundles de navegador.