Conecte seu agente em quatro etapas.
Para Claude, ChatGPT ou Codex, o OAuth é a conexão recomendada porque pode expor com segurança as ferramentas HumanDesign.ai permitidas para o usuário conectado.
1. Adicione o endpoint hospedado
Endpoint
https://mcp.humandesign.ai/Escolha HTTP remoto ou Streamable HTTP. Não adicione /mcp novamente: o endpoint canônico é a raiz do domínio.
2. Autentique-se
Use a ação Authenticate ou Connect do MCP no cliente e conclua o login do HumanDesign.ai no navegador. Usuários do Claude Code podem executar claude mcp login human-design-ai; usuários do Codex podem executar codex mcp login human_design_ai.
Se você precisa somente das seis ferramentas de cálculo e referência, ainda pode usar uma chave de API por meio da autenticação Bearer ou X-Api-Key autenticação.
3. Descubra suas ferramentas
JSON-RPC
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}A descoberta é gratuita. A visibilidade das ferramentas OAuth segue as concessões de recursos determinadas pelo servidor, a assinatura Free/Individual/Personal/Pro do usuário, a função na área de trabalho, a propriedade e as permissões do produto. A visibilidade por chave de API segue o plano de API Free/Creator/Startup/Business separado.
4. Comece pelo seu gráfico principal
Peça ao agente para chamar chart_get_primary. Se não houver um gráfico principal, membros Free, Individual, Personal e Pro podem usar chart_generate: primeiro confira os dados de nascimento normalizados e a prévia de uma unidade; depois, confirme a execução. O gráfico salvo é localizado pela propriedade da conta, nunca por uma busca de nome como “Kyle” ou “My Chart”. Para ler gráficos autorizados de outras pessoas, é necessário Personal ou Pro.
Conexão, initialize, ping, tools/list, consultas à biblioteca, verificações de status e renderização de gráficos existentes não consomem créditos. Um novo cálculo do gráfico principal consome exatamente uma unidade de cálculo; renderizá-lo não gera uma segunda cobrança.
Como funciona a confiabilidade dos cálculos
O agente não calcula o gráfico por conta própria. O HumanDesign.ai valida data, local, fuso horário IANA e horário de verão antes de consumir a cota e, em seguida, retorna o resultado versionado do serviço de cálculo. Locais ambíguos e dados inválidos geram um erro claro sem consumir uma unidade. Se a hora de nascimento for desconhecida, o serviço registra que usou meio-dia local e alerta que detalhes do gráfico sensíveis ao horário podem variar.
Novas tentativas de cálculo seguras
As ferramentas MCP que consomem cota generate_chart, generate_composite_chart, e get_transits exigem uma idempotencyKey. Reutilize a mesma chave com argumentos normalizados idênticos em uma tentativa intencional e use uma nova chave para um novo trabalho. Uma tentativa correspondente não consome cota adicional e pode recalcular o resultado de forma determinística; ela não reproduz byte a byte uma resposta armazenada. Chamadas MCP de trânsito exigem uma data explícita para que uma nova tentativa sempre se refira ao mesmo instante. Clientes REST diretos e Agent HTTP podem enviar Idempotency-Key em operações compatíveis, limitadas e sem streaming; durante a transição de compatibilidade, ela continua opcional, portanto chamadas sem essa chave não conseguem eliminar uma tentativa de transporte duplicada. Batch e SSE rejeitam chaves de repetição fornecidas pelo cliente e não fazem parte deste contrato de deduplicação.
Teste do protocolo bruto
Desenvolvedores com uma chave de API podem inicializar e chamar diretamente uma ferramenta de cálculo:
Inicialização
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}Chamada de cálculo
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "generate_chart",
"arguments": {
"birthDateTime": "1990-05-15T14:30:00",
"timezone": "America/New_York",
"detailLevel": "core",
"idempotencyKey": "chart-1990-05-15-v1"
}
}
}Escolha seu cliente
Claude · Codex · Cursor · VS Code · Downloads de plugins