ONCE

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

O que faz

Registra ações de provedores suportados sob uma chave de operação estável. Solicitações repetidas reutilizam a operação; um resultado incerto permanece incerto até que evidências o resolvam.

Beta pública para desenvolvedores: documentação, cadastro e uso gratuito estão disponíveis. Use sua chave de API do produto para solicitaçõ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 ONCE. 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.

Você também precisa de uma chave secreta de sandbox do Stripe começando com sk_test_ com permissão para criar PaymentIntents. Uma chave publicável não funcionará. O exemplo cria um objeto de teste não confirmado; ele não cobra um cartão. A ONCE recebe essa credencial para a solicitação e não a armazena no ledger.

ONCE_API_KEY=replace_with_your_project_key
STRIPE_TEST_KEY=replace_with_your_Stripe_sandbox_secret_key
ONCE_OPERATION_KEY=quickstart-intent-001

Adicione .env ao .gitignore. Nunca o envie, coloque-o em um bundle de navegador ou cole credenciais em mensagens de suporte. Mantenha a mesma ONCE_OPERATION_KEY para reexecuções deste exemplo; alterá-la cria uma nova operação lógica.

node --env-file=.env once-first-operation.mjs

Como é o sucesso

O script registra um PaymentIntent de teste do Stripe não confirmado, repete a mesma solicitação lógica e verifica se o ID da operação permanece o mesmo. Em seguida, ele lê o ledger. Um estado COMMITTED registra sucesso do provedor; UNKNOWN ou AMBIGUOUS significa parar e inspecionar. Ele nunca chama retry.

A saída esperada inclui PASS:. Leia também as mensagens de estado acompanhantes: uma repetição bem-sucedida por si só não prova um efeito do provedor. O exemplo faz solicitações reais de API e usa um pequeno número de suas unidades de solicitação.

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

Sua conexão com o GitHub

Use um token de granularidade fina limitado ao seu repositório com leitura/gravação de Issues. Forneça Once-GitHub-Token e Once-GitHub-Repository: owner/repository nos cabeçalhos da solicitação. O repositório permanece vinculado à operação. Repetir ou reconciliar exige sua credencial; um novo token pode substituir um expirado, mas não pode redirecionar a operação. Tokens nunca são armazenados no ledger. Criar uma issue é uma gravação real no repositório.

O SDK aceita essas credenciais como seu terceiro argumento de construtor: {githubToken, githubRepository}. Transportes MCP enviam os mesmos cabeçalhos HTTP; credenciais nunca são argumentos de ferramenta. Consultas somente leitura precisam apenas da sua chave ONCE.

Endpoints REST

Endpoint	Comportamento
POST /v1/operations	Cria ou recupera uma operação lógica usando Idempotency-Key.
GET /v1/operations/{id}	Lê o estado durável e a segurança de repetição.
POST /v1/operations/{id}/reconcile	Lê evidências do provedor e atualiza a operação.
POST /v1/operations/{id}/retry	Repete somente quando a evidência registrada permitir.

Comportamento de falha e limites

• Reutilizar uma chave com parâmetros diferentes retorna um conflito sem outra ação do provedor.
• Estados UNKNOWN e AMBIGUOUS nunca permitem reenvio cego. Um objeto de provedor ausente por si só não prova não-confirmação.
• Adaptadores suportados criam PaymentIntents de teste do Stripe não confirmados em seu sandbox e issues do GitHub em um repositório vinculado usando sua credencial de escopo de solicitação. Eles não capturam pagamentos ao vivo nem oferecem acesso HTTP arbitrário.
• A idempotência nativa do provedor pode ser suficiente para uma integração única. A ONCE adiciona um registro de operação durável e estados explícitos de resultado/recuperação para as ações suportadas. Ela não promete efeitos universais de exatamente uma vez.

Os corpos das solicitaçõ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 em vez de uma operação bem-sucedida.

Exemplos executáveis e lista de verificação de integração

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

Quando esta ferramenta ajuda

Use a ONCE quando sua aplicação precisar de um registro durável de ações de provedores suportados e decisões explícitas de recuperação após um timeout ou falha. A idempotência nativa do provedor pode ser suficiente para uma integração única e direta; a ONCE adiciona um ID de operação consultável, estado registrado e reconciliação baseada em evidências. Ela não torna ações arbitrárias exatamente uma vez.

Antes de colocar em um worker

• Persista sua chave de operação lógica antes do envio e reutilize-a com parâmetros idênticos.
• Salve o ID da operação retornado para que outro processo possa inspecionar o mesmo registro do ledger.
• Trate UNKNOWN e AMBIGUOUS como não resolvidos; reconcilie com evidências antes de considerar repetição.
• 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. Credenciais Stripe devem ser chaves secretas de teste; credenciais ao vivo não são aceitas.
HTTP 409	Parâmetros diferentes com uma chave lógica existente conflitam. Restaure os parâmetros originais; nunca altere chaves apenas para contornar um resultado incerto.
HTTP 429	Verifique o uso mensal e os limites de taxa. Aguarde antes de outra tentativa. A reconciliação da ONCE tem uma reserva mensal separada de 100 solicitações; um erro de cota nunca prova uma repetição segura.
Timeout ou exemplo interrompido	Preserve a chave lógica. Reexecute com os mesmos parâmetros para recuperar essa operação; não chame retry cegamente.

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

Notas de engenharia

Um timeout não informa se uma ação aconteceu: 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://once.aiagenthuddle.com/mcp
Cabeçalho	Authorization: Bearer YOUR_ONCE_API_KEY
Ferramentas esperadas	once_create, once_get, once_retry, once_reconcile

Use a configuração de credenciais privadas do seu cliente. Um cliente que suporta apenas OAuth não pode autenticar neste endpoint de chave de API. Se a descoberta retornar 401, verifique o cabeçalho antes de invocar ferramentas. Credenciais de provedor devem usar os cabeçalhos HTTP dedicados descritos acima, nunca argumentos de ferramenta. Comece com a descoberta; criar uma issue grava no seu repositório.

JavaScript · Node.js

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

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

const once = new OnceClient(
  'https://once.aiagenthuddle.com',
  process.env.ONCE_API_KEY,
  { stripeTestKey: process.env.STRIPE_TEST_KEY }
);

const operation = await once.create(
  'order-123-intent', 'stripe', 'create_payment_intent',
  { amount: 100, currency: 'gbp' }
);
// Preserve the operation ID. Inspect before any retry.
console.log(operation);

MCP autenticado sem estado está disponível em /mcp. Ferramentas: once_create, once_get, once_retry, once_reconcile. Clientes oficiais atuais e legados passaram em verificações protegidas hospedadas. 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 para o seu projeto do lado do servidor. Nenhum pacote npm é publicado. Mantenha credenciais fora de bundles de navegador.