Documentação para desenvolvedores

MCP

Conecte Claude, Codex e outros clientes MCP às suas notas do Alt.

O Alt oferece um servidor MCP (Model Context Protocol) hospedado. Clientes com suporte a OAuth podem entrar pelo navegador; chaves de API continuam disponíveis como alternativa. Os dois métodos aplicam os mesmos scopes somente leitura e limites de workspace.

Comece por aqui

Execute o assistente de configuração interativo — ele salva a chave de API, conecta o MCP e pode passar o trabalho ao seu agente:

npx
npx altalt --mcp-only

Conectar com o conector do Claude

O Alt está listado no diretório de conectores do Claude, então na maioria dos casos você não precisa do endpoint abaixo. No Claude, abra Customize → Connectors, busque por Alt e selecione Connect.

  • Aprove o acesso na tela de consentimento do próprio Alt e escolha o único espaço que o conector poderá ler: suas notas pessoais ou um canal.
  • Nada para colar e nenhuma chave de API para criar. O Claude se registra sozinho via OAuth.
  • Exige uma conta Alt em um plano pago. Contas gratuitas chegam à tela de consentimento, mas recebem o erro plan_required ao aprovar.
  • Somente leitura por design: lista e pesquisa notas e lê transcrições e resumos, nunca escreve. Pode ser revogado a qualquer momento no console da conta.
Ver no diretório de conectores

1. Conecte com OAuth (recomendado)

Adicione o endpoint sem cabeçalhos. Seu cliente descobre o servidor de autorização do Alt, registra-se e abre a tela de consentimento no navegador.

  • O Alt oferece Dynamic Client Registration e PKCE, então clientes compatíveis configuram o OAuth automaticamente.
  • Revise no navegador os scopes somente leitura e o workspace solicitados antes de aprovar o acesso.
  • Conectar exige uma conta Alt em um plano pago. Contas gratuitas chegam à tela de consentimento, mas recebem o erro plan_required ao aprovar.

2. Conecte seu cliente

Use a configuração apenas com URL para OAuth. Não é necessário OAuth client ID nem secret; use uma chave de API somente se o cliente não conseguir concluir o OAuth.

MCP URL
https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

Use um conector personalizado apenas para acessar outro ambiente do Alt: abra Customize → Connectors → Add custom connector, informe o endpoint acima e deixe o client ID e o secret do OAuth vazios.

Claude Code

shell
claude mcp add --transport http alt https://mcp.altalt.io/mcp

Depois de adicionar o servidor, abra /mcp no Claude Code, selecione Alt e conclua a autenticação no navegador.

Codex CLI

shell
codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt
config.toml
# ~/.codex/config.toml
[mcp_servers.alt]
url = "https://mcp.altalt.io/mcp"

Adicionar o servidor normalmente conclui a autenticação no navegador. Se ela não iniciar, execute codex mcp login alt.

Cursor

Adicionar ao Cursor

Instalação em um clique apenas com a URL. Nas configurações MCP do Cursor, selecione Connect ou Needs authentication e aprove o consentimento no navegador.

Outros clientes e alternativa com chave de API

Comece com a configuração OAuth apenas com URL. Se o cliente não oferecer suporte a MCP OAuth, use a configuração com chave de API Bearer.

OAuth
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp"
    }
  }
}
Chave de API
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp",
      "headers": { "Authorization": "Bearer alt_live_..." }
    }
  }
}

Chaves de API continuam disponíveis para automação e clientes antigos. Crie uma no console da conta, conceda apenas os scopes necessários, não a deixe em configurações compartilhadas e consulte Segurança para gerenciá-la.

3. Ferramentas

Sete ferramentas somente leitura, que aplicam os mesmos scopes da API REST.

  • list_notes — Lista as notas que esta conexão pode ler, com paginação por cursor. Por padrão, a atualização mais antiga primeiro; com order=newest_first, as mais recentes primeiro. Filtre por updated_after, fim da gravação (ended_after / ended_before), channel_id ou folder_id (notes:read).
  • get_note — Busca os metadados de uma nota: título, prontidão de transcrição/resumo, timestamps (notes:read).
  • get_note_transcript — Busca a transcrição completa em segmentos com tempo e rótulos de falante (transcripts:read).
  • get_note_summary — Busca o resumo de IA em Markdown (summaries:read).
  • search_notes — Encontra notas cujo título, transcrição ou resumo contém uma palavra ou frase. Resultados na transcrição trazem o momento e o falante. Transcrições e resumos só são pesquisados com transcripts:read / summaries:read (notes:read).
  • list_folders — Lista as pastas que esta conexão pode ler. O id de uma pasta serve como folder_id em list_notes (notes:read).
  • get_account_info — Mostra a qual conta Alt a conexão pertence, se ela lê notas pessoais, um canal ou um workspace inteiro, e seus canais legíveis e permissões. Útil quando notas esperadas não aparecem (notes:read).

As notas aparecem quando uma gravação termina ou um resumo é gerado — notas apenas de memo não são exportadas. Antes de o conteúdo ficar pronto, as ferramentas retornam transcript_not_ready / summary_not_ready, para que os agentes tentem novamente depois.