Como usar a API e o servidor MCP do TrainerPlan

A API do TrainerPlan permite que as tuas próprias ferramentas leiam a tua conta de treinador e planeiem para os teus atletas: um assistente de IA como o Claude, o ChatGPT ou o Cursor através do nosso servidor MCP, um script ou uma folha de cálculo. Está incluída no plano Elite. Este artigo mostra como criar uma chave, ligar um assistente e fazer o teu primeiro pedido.

O que podes fazer com ela

• Ler os teus atletas, os calendários deles (treinos planeados e realizados, com os seus passos), eventos, notas, comentários, zonas de treino, fitness, fadiga e forma, métricas diárias como o peso, o sono e a HRV, e a tua biblioteca de treinos.
• Fazer alterações, com uma chave que o permita: planear treinos com passos estruturados, copiar treinos da tua biblioteca, adicionar notas e eventos, e comentar uma sessão. O atleta é notificado e vê a alteração no calendário, tal como se a tivesses feito no TrainerPlan.

Antes de começar

• A API e o servidor MCP fazem parte do plano Elite. No período de teste ou noutro plano, a página API / MCP explica como mudar de plano.
• Só o proprietário da conta e os administradores da equipa podem criar chaves.

1. Cria uma chave

1. Abre o teu perfil e escolhe API / MCP no menu da esquerda, ou vai a app.trainerplan.co/trainer/api, e seleciona Criar chave.
2. Dá-lhe um nome que diga o que a vai usar, por exemplo «Relatório semanal».
3. Escolhe uma Validade se quiseres que a chave deixe de funcionar sozinha ao fim de 30 dias, 90 dias ou 1 ano.
4. Marca Permitir que esta chave faça alterações só se a ferramenta precisar de planear ou editar. Sem essa opção, a chave só pode ler.
5. Da primeira vez, aceita os termos da API. Só o fazes uma vez para a tua conta.
6. Seleciona Criar chave e depois Copiar. A chave só é mostrada uma vez, por isso guarda-a num local seguro.

Uma chave dá acesso a todos os atletas da tua conta, por isso trata-a como uma palavra-passe. Usa uma chave diferente para cada ferramenta: podes ter até 10 e podes Revogar uma em qualquer momento sem afetar as outras.

2. Liga um assistente de IA (MCP)

Os assistentes compatíveis com o Model Context Protocol (MCP), como o Claude, o ChatGPT, o Cursor ou o VS Code, ligam-se diretamente ao TrainerPlan: tudo o que a API faz passa a ser uma ferramenta que o assistente pode usar, sem escrever código nem carregar nenhum ficheiro. O endereço do servidor também está na página API / MCP:

https://api.trainerplan.co/api/v1/mcp

Identifica-se com a tua chave e só faz o que a chave permite: com uma chave só de leitura, o assistente só pode ler. A maioria dos assistentes permite enviar a chave como cabeçalho. No Claude Code, por exemplo:

claude mcp add --transport http trainerplan https://api.trainerplan.co/api/v1/mcp \

  --header "Authorization: Bearer YOUR_API_KEY"

Se um assistente só pedir um endereço (um conector personalizado no Claude ou no ChatGPT, por exemplo), acrescenta a tua chave no fim: https://api.trainerplan.co/api/v1/mcp/YOUR_API_KEY. Esse endereço funciona como a própria chave: mantém-no privado e revoga a chave se alguma vez for partilhado.

Depois pergunta por palavras tuas, por exemplo «Quem falhou uma sessão esta semana?» ou «Planeia 5 x 1 km para a Laura na quinta-feira». O que o assistente alterar chega aos calendários e dispositivos dos teus atletas como se o tivesses feito tu. Tem instruções para te consultar antes de alterar alguma coisa, mas dá-lhe uma chave só de leitura a menos que queiras que planeie, e confirma o que planeia antes de confiar nisso.

3. Usa-a a partir dos teus próprios scripts

Envia a chave no cabeçalho Authorization. Este pedido lista os teus atletas:

curl https://api.trainerplan.co/api/v1/athletes \
  -H "Authorization: Bearer YOUR_API_KEY"

Todos os endereços começam por https://api.trainerplan.co/api/v1. A lista completa do que podes pedir, com um exemplo de cada pedido, está em Documentação da API, a ligação no fim da página da API.

Limites e utilização

Cada chave pode fazer 120 pedidos por minuto, dos quais 30 podem ser alterações. Um pedido acima do limite recebe um erro 429: espera um minuto e tenta de novo. Por baixo das tuas chaves, Utilização nos últimos 30 dias mostra os pedidos de cada dia e quantos foram recusados pelo limite.

Convém saber

• De um atleta que ainda não aceitou o teu convite, a API só devolve o que tu próprio adicionaste.
• As notas que um atleta mantém privadas não são devolvidas.
• Se achares que uma chave ficou exposta, revoga-a na página da API e cria outra.

Dúvidas? Escreve-nos para info@trainerplan.co.