> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useweve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar agentes (MCP)

> Claude, ChatGPT, Cursor e outros agentes operando um club pelo Model Context Protocol.

O club é exposto como um **servidor MCP**: um agente conectado lista cursos, acompanha alunos,
responde comentários, monta campanhas e cria conteúdo — com as mesmas regras do painel.

```
https://api.useweve.com/mcp
```

É um servidor **Streamable HTTP sem estado**: cada chamada é um `POST` independente, e o `GET`
(o fluxo aberto do servidor para o cliente) responde `405`, como a especificação prevê para quem
não o oferece.

## O que o agente pode fazer

Uma conexão vale para **um club**, age **em nome de uma pessoa** e com o **papel** que ela tem
nele. Nada fica maior do que a própria pessoa: quem não administra o club continua sem
administrar pelo agente, e o plano do club vale igual — recurso fora do plano responde `402`.

Toda ferramenta executa as mesmas operações que o painel usa, pelo mesmo caminho: escopo,
papel, plano, limites e validação são os de sempre.

**Quem do time pode conectar** é um ajuste do club, em **Ajustes › MCP para IA**: ninguém,
só quem administra (o padrão) ou todo o time. Ele vale a cada chamada: fechar corta os agentes na
hora, e reabrir os devolve.

| escopo | o que libera |
| - | - |
| `read` | As ferramentas de consulta. A conexão só de leitura nem vê as outras |
| `write` | Criar, alterar, publicar, enviar |

## Conectar por OAuth

Clientes que falam OAuth (Claude, ChatGPT, Cursor, VS Code, o Inspector do MCP) só precisam do
endereço. Na primeira chamada o servidor responde `401` apontando para os metadados, e o cliente
conduz o resto sozinho:

1. descobre o servidor de autorização em
   `/.well-known/oauth-protected-resource/mcp` ([RFC 9728](https://datatracker.ietf.org/doc/rfc9728))
   e os endpoints em `/.well-known/oauth-authorization-server`
   ([RFC 8414](https://datatracker.ietf.org/doc/rfc8414));
2. se registra em `/oauth/register` ([RFC 7591](https://datatracker.ietf.org/doc/rfc7591));
3. abre o navegador em `/oauth/authorize`, que leva à tela de consentimento do painel — é ali
   que a pessoa **escolhe o club** e o que concede;
4. troca o código por token em `/oauth/token`, com PKCE.

O token de acesso vale **uma hora** e o de renovação, **60 dias** a partir do último uso — o
agente em uso nunca pede login de novo. O de renovação **gira a cada uso**: apresentar um que já
foi trocado derruba a conexão inteira, porque é o sinal de que ele vazou.

> [!NOTE]
>
> PKCE com `S256` é obrigatório. O endereço de retorno precisa ser `https`, o loopback
> (`http://127.0.0.1` ou `http://localhost`, em qualquer porta) ou o esquema do aplicativo
> (`cursor://…`), e é comparado **exatamente** com o registrado.

## Chave de API

Para o agente que não faz OAuth — uma automação no n8n, um script, um cliente configurado à
mão —, crie uma chave em **Ajustes › Chaves de API** e mande-a no cabeçalho:

```bash theme={null}
claude mcp add --transport http weve https://api.useweve.com/mcp \
  --header "Authorization: Bearer weve_sk_…"
```

A chave aparece **uma vez**, age em nome de quem a criou, no club onde foi criada, e pode ter
prazo ou não. Até 20 por club. A mesma chave abre a [API REST](https://docs.useweve.com/essentials/api.md).

## Quando o acesso cai

A conexão e a chave param de valer, na chamada seguinte, quando:

* alguém a revoga em **Ajustes › MCP para IA** (conexão) ou **Ajustes › Chaves de API** (chave) —
  quem administra revoga qualquer uma do club;
* o ajuste do club deixa de permitir agentes para aquela pessoa — aqui a conexão fica parada, e
  volta a responder se o ajuste for reaberto;
* a pessoa sai do club ou é removida do time;
* a senha da pessoa é redefinida pelo link de e-mail — quem recupera uma conta não pode deixar
  para trás um agente que outra pessoa conectou com ela;
* o prazo da chave, ou os 60 dias sem uso da conexão, passam.

## As ferramentas

A lista de verdade é a que o servidor devolve em `tools/list`, com o schema de entrada de cada
ferramenta. ✎ marca as que escrevem (escopo `write`).

| área | ferramentas |
| - | - |
| Clube | `get_club`, `get_club_overview`, `get_club_engagement`, `get_course_funnel`, `get_club_billing` |
| Relatórios | `list_report_kinds`, `create_report`✎, `list_reports`, `get_report` |
| Conteúdo | `list_courses`, `get_course`, `list_lessons`, `create_course`✎, `update_course`✎, `create_module`✎, `update_module`✎, `create_lesson`✎, `get_lesson`, `update_lesson`✎, `write_lesson_text`✎, `set_lessons_status`✎, `reorder_course`✎, `create_course_with_structure`✎, `duplicate_course`✎, `duplicate_module`✎, `duplicate_lesson`✎ |
| Repositórios | `list_repositories`, `get_repository`, `create_repository`✎, `update_repository`✎, `set_repository_files`✎, `set_repository_structure`✎ |
| Trilhas | `list_playlists`, `get_playlist`, `create_playlist`✎, `update_playlist`✎, `set_playlist_items`✎ |
| Biblioteca | `list_media`, `add_external_media`✎, `get_video_transcript` |
| Certificados e trabalhos | `get_course_certificate`, `set_course_certificate`✎, `list_assignment_submissions`, `get_assignment_submission`, `review_assignment_submission`✎, `list_certificates`, `get_certificate`, `reissue_certificate`✎, `revoke_certificate`✎, `restore_certificate`✎ |
| Alunos e acesso | `list_students`, `get_student`, `list_student_courses`, `invite_student`✎, `send_student_access_link`✎, `list_deliveries`, `grant_access`✎, `revoke_access`✎, `extend_access`✎, `change_access_start`✎, `list_expiring_access`, `list_student_tags`, `tag_student`✎, `untag_student`✎, `update_student`✎, `list_student_activity`, `list_student_emails`, `list_student_automations`, `list_student_quizzes`, `list_student_study_days`, `list_student_mentorships`, `rename_student_tag`✎, `delete_student_tag`✎, `grant_access_batch`✎, `revoke_access_batch`✎, `extend_access_batch`✎, `move_enrollment`✎, `start_bulk_action`✎, `get_bulk_action` |
| Links de cadastro | `list_registration_links`, `create_registration_link`✎, `update_registration_link`✎, `delete_registration_link`✎, `rotate_registration_link`✎ |
| Vendas | `list_sales_events`, `reprocess_sales_event`✎ |
| Produtos e turmas | `list_products`, `list_sales_connections`, `create_product`✎, `update_product`✎, `set_product_deliveries`✎, `add_product_external_id`✎, `remove_product_external_id`✎, `create_delivery`✎, `update_delivery`✎, `set_delivery_deliverables`✎, `list_cohorts`, `create_cohort`✎, `update_cohort`✎, `reapply_cohort`✎, `list_cohort_students`, `extend_cohort`✎, `revoke_cohort`✎ |
| Comentários | `list_inbox_threads`, `get_inbox_thread`, `reply_to_thread`✎, `mark_thread`✎, `moderate_thread`✎, `update_comment`✎ |
| Comunidade | `get_community`, `list_community_posts`, `reply_to_post`✎, `create_community_post`✎, `moderate_community_post`✎ |
| Gamificação | `get_gamification`, `update_gamification`✎, `set_gamification_levels`✎, `get_gamification_ranking`, `get_student_points`, `adjust_student_points`✎ |
| Campanhas | `list_campaigns`, `get_campaign`, `create_campaign`✎, `update_campaign`✎, `count_campaign_audience`, `send_campaign_test`✎, `schedule_campaign`✎, `unschedule_campaign`✎, `pause_campaign`✎, `resume_campaign`✎, `cancel_campaign`✎, `delete_campaign`✎, `list_campaign_deliveries` |
| Automações | `list_workflows`, `get_workflow`, `create_workflow`✎, `update_workflow`✎, `publish_workflow`✎, `send_workflow_email_test`✎, `archive_workflow`✎, `delete_workflow`✎, `list_workflow_runs`, `get_workflow_stats`, `pause_workflow`✎, `resume_workflow`✎, `get_workflow_run`, `cancel_workflow_run`✎, `list_workflow_versions` |
| Mentoria | `list_mentorships`, `list_mentees`, `get_mentee`, `get_mentee_plan`, `create_mentee_goal`✎, `create_mentee_task`✎, `list_mentorship_playbooks`, `create_mentorship_playbook`✎, `update_mentorship_playbook`✎, `set_playbook_tasks`✎, `list_mentorship_sessions`, `get_mentorship`, `create_mentorship`✎, `update_mentorship`✎, `set_mentorship_stages`✎, `update_mentee`✎, `grant_mentorship_credits`✎, `revoke_mentorship_credits`✎, `list_mentee_notes`, `create_mentee_note`✎, `update_mentee_goal`✎, `update_mentee_task`✎, `delete_mentee_goal`✎, `delete_mentee_task`✎, `recommend_to_mentee`✎, `list_mentee_sessions`, `create_mentorship_session`✎, `get_mentorship_session`, `update_mentorship_session`✎, `list_mentors`, `list_mentor_slots`, `list_mentorship_ratings` |
| Lives | `list_live_channels`, `list_lives`, `get_live`, `create_live`✎, `update_live`✎, `create_live_channel`✎, `update_live_channel`✎, `set_live_hosts`✎, `start_live`✎, `end_live`✎, `list_live_attendance`, `list_live_messages` |
| Agentes de IA | `list_agents`, `get_agent`, `create_agent`✎, `update_agent`✎, `get_agent_knowledge`, `set_agent_knowledge`✎, `list_agent_knowledge_sources`, `get_course_assistant`, `set_course_assistant`✎, `get_repository_assistant`, `set_repository_assistant`✎, `get_ai_usage` |
| Área do aluno | `list_classroom_banners`, `create_classroom_banner`✎, `update_classroom_banner`✎, `reorder_classroom_banners`✎, `list_stories`, `get_story`, `create_story`✎, `update_story`✎, `set_story_frames`✎, `reorder_stories`✎, `delete_story`✎, `get_classroom_menu`, `set_classroom_menu`✎, `reset_classroom_menu`✎, `get_classroom_page`, `set_classroom_page`✎, `reset_classroom_page`✎ |
| Ajustes do clube | `update_club_branding`✎, `rename_club`✎, `get_club_settings`, `update_club_settings`✎, `list_club_terms`, `get_club_term`, `save_club_term`✎, `list_club_emails`, `update_club_email`✎, `reset_club_email`✎, `send_club_email_test`✎, `get_club_welcome`, `set_club_welcome`✎, `get_club_welcome_stats`, `list_club_extensions`, `enable_club_extension`✎, `disable_club_extension`✎ |

As que o aluno sente — enviar e-mail, publicar em público, revogar acesso, ligar certificado —
vêm marcadas como destrutivas, e o cliente pede confirmação antes de executá-las.

### O que não está ao alcance de nenhum agente

Por desenho, e não por falta de ferramenta: emitir, listar ou revogar credenciais; entrar na área
do aluno **como** o aluno; ver ou trocar a senha dele; convidar ou remover alguém do time; mudar
plano, cobrança ou domínio; conectar plataforma de venda ou webhook de saída (o segredo passaria
pelo modelo); anonimizar aluno; apagar mídia; importar alunos em lote. Esses ficam no painel, com
uma pessoa na frente.

## Erros

Erro de uma operação volta como resultado da ferramenta com `isError`, em texto que o modelo lê e
corrige: `erro 422 (invalid_block): …`. O código entre parênteses é estável — ver
[Erros](https://docs.useweve.com/essentials/errors.md). Argumento que não está no schema é recusado **antes** de chegar à
operação, com o nome do campo.

O servidor tem teto de **300 chamadas por minuto por conexão**, por cima do teto de escrita do
club ([Limites](https://docs.useweve.com/essentials/rate-limits.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.