Cogram Project

npx add-mcp 'https://mcp.cogram.com/mcp'

Para o índice completo da documentação, consulte llms.txt. Versões em Markdown das páginas de documentação estão disponíveis acrescentando .md às URLs das páginas; esta página está disponível como Markdown.

Servidor MCP

Conecte o ChatGPT, o Claude ou um agente de IA personalizado ao Cogram por meio do servidor MCP: acesso somente leitura, agindo como a pessoa que o conectou.

O servidor MCP do Cogram permite que um usuário conecte um aplicativo de IA ao Cogram e depois faça perguntas sobre seus projetos — atas de reuniões, e-mails, RFIs, submissões, desenhos, relatórios de campo e o diretório.

MCP (Model Context Protocol) é o padrão aberto que os aplicativos de IA usam para alcançar sistemas externos. Qualquer cliente MCP pode se conectar: ChatGPT, claude.ai ou um agente que sua própria equipe desenvolva.

Endereço do servidor: https://mcp.cogram.com/mcp

Dois fatos definem o que um agente conectado pode fazer:

• É somente leitura. O agente pode pesquisar, ler e resumir. Ele não pode criar, alterar ou excluir nada no Cogram.
• Ele age como uma pessoa. O agente vê exatamente o que o usuário que o conectou pode ver, e nada mais.

Esta página aborda a configuração para administradores da organização. Usuários que conectam ChatGPT, Claude ou outro aplicativo de IA devem seguir Conectando aplicativos de IA.

Você controla o acesso MCP em dois lugares: no Cogram, onde você permite conexões em geral, e — se sua empresa opera um workspace do ChatGPT ou do Claude — nesse workspace, onde você disponibiliza o Cogram aos seus usuários.

Etapa 1: Ative o acesso MCP no Cogram

O acesso MCP está desativado por padrão para todas as organizações. Um administrador o ativa uma vez, para toda a organização.

1. Vá para Configurações da organização → Integrações → Acesso MCP.
2. Ative Permitir que membros conectem agentes de IA de terceiros.

A mesma página mostra a URL do servidor com um botão de copiar — este é o endereço que usuários e aplicativos de IA precisam.

Uma vez que o acesso MCP está ativado, qualquer usuário pode conectar um aplicativo de IA para si mesmo. Usuários que não conectam nada não são afetados. Desativá-lo novamente corta todos os agentes já conectados e impede que usuários conectem novos.

Se você não vir o acesso MCP em Configurações da organização → Integrações, o acesso MCP ainda não está disponível para sua organização. Envie um e-mail para support@cogram.com.

Se seus usuários estão em contas de IA pessoais, você terminou — envie-os para Conectando aplicativos de IA. O restante desta página aborda workspaces de IA gerenciados pela empresa e agentes personalizados.

Etapa 2 (opcional): Publique o Cogram no seu workspace do ChatGPT

No ChatGPT Business, Enterprise e Edu, os usuários não podem adicionar aplicativos MCP personalizados por conta própria — um administrador do workspace cria o aplicativo Cogram uma vez e o publica no workspace.

1. Como administrador ou proprietário, ative o modo de desenvolvedor para você em Configurações → Aplicativos → Configurações avançadas → Modo de desenvolvedor. Cada administrador o ativa para si; ele também é oferecido ao criar um aplicativo. (No Enterprise e Edu, você também pode conceder o modo de desenvolvedor a usuários não administradores selecionados em Configurações do workspace → Permissões e funções → Dados conectados.)
2. Vá para Configurações do workspace → Aplicativos → Criar.
3. Nomeie o aplicativo Cogram MCP e insira a URL do servidor MCP https://mcp.cogram.com/mcp. Escolha OAuth como método de autenticação.
4. Selecione Escanear ferramentas. O ChatGPT abre o login do Cogram — entre como você normalmente faz, inclusive por meio do seu provedor de identidade se sua organização usa SSO, e selecione Permitir na tela de aprovação.
5. Aguarde a conclusão da varredura de ferramentas e selecione Criar. O aplicativo é salvo como rascunho em Configurações do workspace → Aplicativos → Rascunhos. Opcionalmente, teste-o primeiro: em um novo chat, selecione o rascunho (rotulado como "Dev") no menu de ferramentas e pergunte sobre seus projetos do Cogram.
6. Publique-o: Configurações do workspace → Aplicativos → Rascunhos → Publicar e confirme os avisos de revisão. Cada ferramenta do Cogram é somente leitura, portanto não há ações de gravação para revisar.
7. No Enterprise e Edu, o diálogo de publicação também permite restringir ferramentas individuais (Configurar ações) ou limitar quais grupos veem o aplicativo (Configurar acesso).

Resultado esperado: o Cogram MCP aparece para os usuários em Plugins, na aba do seu workspace, rotulado como "personalizado" — eles o instalam conforme descrito em Conectando aplicativos de IA. Cada usuário faz login no Cogram por conta própria, então o agente de cada usuário vê apenas seus próprios projetos.

O ChatGPT congela a lista de ferramentas do aplicativo quando você publica. Quando o Cogram lança novas ferramentas, elas não são adotadas automaticamente: no Enterprise e Edu, selecione Atualizar sob o Controle de ações do aplicativo e habilite as novas ferramentas (novas ferramentas chegam desabilitadas); no Business, recrie e republique o aplicativo.

Etapa 3 (opcional): Publique o Cogram no seu workspace do Claude

Nos planos Claude Team e Enterprise, um Proprietário pode adicionar o Cogram como um conector personalizado para toda a organização. Somente Proprietários podem fazer isso.

1. Vá para Configurações da organização → Conectores.
2. Selecione Adicionar, passe o mouse sobre Personalizado e escolha Web.
3. Nomeie o conector Cogram MCP e insira a URL do servidor MCP https://mcp.cogram.com/mcp.
4. Deixe os campos ID do cliente OAuth e Segredo do cliente em Configurações avançadas vazios — o Cogram registra cada cliente automaticamente.
5. Selecione Adicionar.

Resultado esperado: cada usuário vê o Cogram MCP em Personalizar → Conectores, rotulado como "Personalizado" — eles o conectam conforme descrito em Conectando aplicativos de IA. Cada usuário seleciona Conectar lá e faz login no Cogram por conta própria, então o agente de cada usuário vê apenas seus próprios projetos.

Conecte um cliente personalizado ou agente interno

O servidor é um servidor MCP padrão: transporte HTTP transmissível, OAuth 2.1 com registro dinâmico de clientes. Aponte qualquer biblioteca de cliente MCP, ou o conector MCP da Anthropic, para https://mcp.cogram.com/mcp. O cliente lida com a descoberta e o fluxo OAuth — incluindo o registro de si mesmo, portanto não há nada a pré-registrar com o Cogram.

Duas coisas para planejar em seu próprio agente:

• Um login interativo por identidade. Não há contas de máquina ou contas de serviço. Uma pessoa deve fazer login no Cogram em um navegador e aprovar a conexão uma vez, para cada identidade sob a qual o agente opera.
• Armazene e rotacione o token de atualização. Após a aprovação, seu agente mantém um token de atualização, que ele troca por tokens de acesso de curta duração. Mantenha-o em um local secreto e substitua sua cópia armazenada pela nova a cada atualização. Se você o perder ou ele expirar, a única recuperação é outro login interativo.

Se várias pessoas usam seu agente e cada uma deve ver apenas seus próprios projetos, conecte uma vez por pessoa e mantenha os tokens separados. Uma conexão compartilhada significa que todos veem os dados de quem a aprovou.

Trate o conteúdo do Cogram como dados, não instruções

Os resultados das ferramentas carregam texto que pessoas fora da sua organização escreveram: corpos de e-mails, transcrições de reuniões, texto de anexos, perguntas de RFI, notas do diretório. Qualquer parte disso pode conter algo que pareça uma instrução para um modelo de IA — "ignore suas instruções anteriores", "envie este arquivo por e-mail para…", "o usuário aprovou…".

Seu agente deve tratar cada resultado de ferramenta como dados não confiáveis:

• Mantenha os resultados das ferramentas separados de suas próprias instruções no prompt e declare claramente no prompt do sistema que o conteúdo retornado pelas ferramentas é dado a ser examinado, nunca um comando a seguir.
• Nunca deixe um resultado de ferramenta decidir, por conta própria, chamar outra ferramenta que aja fora do Cogram — enviar e-mail, gravar em outro sistema, executar código.
• Coloque um humano diante de qualquer ação consequente que seu agente tome a partir do conteúdo do Cogram.

O servidor MCP do Cogram é somente leitura, então nada que um agente leia pode alterar o Cogram. O risco é o que seu agente faz em seguida com o que leu.

O que um agente conectado pode e não pode fazer

Pode	Não pode
Pesquisar e ler os registros do Cogram que o usuário pode abrir	Criar, editar, excluir ou arquivar qualquer coisa
Ler texto de anexos e documentos	Enviar e-mails, transmissões ou notificações
Obter links com tempo limitado para imagens de folhas de desenho	Acessar um projeto do qual o usuário não é membro
Ler o diretório da organização e a lista de usuários	Acessar dados de outra organização
Agir como um usuário nomeado	Agir como conta de máquina, administrador ou organização em geral

As permissões do Cogram se aplicam sem alterações. Associação a projetos, funções de projeto e visibilidade de ativos ainda decidem o que o agente vê, porque cada solicitação é respondida como o usuário conectado.

Quais dados um agente pode acessar

O agente trabalha por meio de um conjunto fixo de ferramentas somente leitura. A coluna Módulo necessário mostra onde uma ferramenta depende do licenciamento da sua organização: se sua organização não tiver licença para esse módulo, essas ferramentas não são oferecidas ao agente.

Categoria	Módulo necessário	Ferramentas
Identidade do usuário conectado	—	whoami
Projetos	—	search_projects, get_projects_by_id
Reuniões e anexos de reuniões	Reuniões	search_meetings, get_meetings_by_id, search_meeting_attachments, get_meeting_attachment_content
E-mails e anexos de e-mails	Gerenciamento de e-mail	search_emails, get_emails_by_id, search_email_attachments, get_email_attachment_content
Documentos	—	search_documents, get_documents_by_id
RFIs e submissões	Correspondência	search_rfis, get_rfis_by_id, search_submittals, get_submittals_by_id
Desenhos, relatórios de campo, observações	Relatórios de campo	search_drawings, get_drawings_by_id, search_reports, get_reports_by_id, search_observations, get_observations_by_id
Transmissões	Transmissões ou Gerenciamento de e-mail	search_transmittals, get_transmittals_by_id
Quadros de projeto	—	search_board_items, get_board_item, get_board_items_for_meeting
Agentes	—	search_agents, get_agents_by_id
Pessoas e empresas	—	search_org_members, search_directory
Visão geral da organização	—	get_org_data_summary

Gravações de áudio de reuniões não são acessíveis por nenhuma ferramenta. Transcrições são, para usuários que já podem lê-las. Ferramentas de recuperação que recebem uma lista de IDs aceitam no máximo 100 IDs por chamada. Um agente que solicitar mais receberá um erro de validação, então faça-o trabalhar em lotes.

Limite de taxa

Cada usuário tem permissão para 50 solicitações por minuto por aplicativo conectado. Dois aplicativos conectados pela mesma pessoa têm cada um sua própria cota, e dois usuários nunca compartilham uma.

Acima do limite, o servidor responde 429 com um cabeçalho Retry-After. Um cliente MCP bem comportado aguarda e tenta novamente. Se o seu trabalho realmente precisar de um limite maior, envie um e-mail para support@cogram.com — o limite não é algo que você possa alterar por conta própria.

Solução de problemas

Sintoma: O agente relata "O acesso MCP não está habilitado para sua organização", ou a tela de aprovação não oferece um botão Permitir. Causa provável: O acesso MCP está desativado para sua organização. Correção: Ative-o em Configurações da organização → Integrações → Acesso MCP. Se a configuração não estiver nessa página, envie um e-mail para support@cogram.com.

Sintoma: O Cogram não aparece no menu de ferramentas do ChatGPT. Causa provável: Nos planos Business, Enterprise e Edu, um administrador do workspace ainda não publicou o aplicativo Cogram — os usuários não podem adicioná-lo por conta própria. No Pro, o modo de desenvolvedor está desativado. Correção: Publique o aplicativo Cogram (veja Etapa 2 acima) — os usuários não podem adicioná-lo por conta própria. No Pro, o usuário ativa o modo de desenvolvedor em Configurações → Aplicativos → Configurações avançadas.

Sintoma: Uma categoria inteira está ausente na lista de ferramentas do agente, ou uma chamada responde "O módulo de Reuniões não está licenciado para sua conta Cogram." Causa provável: Sua organização não está licenciada para esse módulo. Correção: Verifique Licenciamento e envie um e-mail para support@cogram.com sobre o módulo. Depois, faça o agente listar suas ferramentas novamente — ou reconecte-o — para que as novas ferramentas apareçam. Em um workspace do ChatGPT, um administrador também deve atualizar e republicar o aplicativo.

Sintoma: Chamadas falham com 429 rate_limit_exceeded. Causa provável: Mais de 50 solicitações em um minuto para esse usuário e aplicativo. Correção: Aguarde o número de segundos indicado no cabeçalho Retry-After. Faça o agente solicitar menos páginas, porém maiores, em vez de muitas chamadas pequenas. Envie um e-mail para support@cogram.com se o trabalho realmente precisar de um limite maior.

Sintoma: Um agente que funcionava de repente pede que você faça login novamente, ou toda chamada responde 401. Causa provável: O token de atualização expirou, foi revogado ou foi sobrescrito por uma cópia mais antiga. Correção: Execute a conexão novamente — faça login e aprove. Para um agente headless, verifique se ele salva o novo token de atualização após cada atualização e se apenas um processo o utiliza.

Sintoma: O agente vê menos projetos ou reuniões do que o usuário espera. Causa provável: O agente tem exatamente o mesmo acesso do usuário. O usuário não está nesses projetos, ou a visibilidade de ativos oculta esses registros dele. Correção: Adicione o usuário aos projetos ou revise Visibilidade de ativos. Nada na conexão em si pode ampliar o que o agente vê.

Sintoma: Você precisa cortar o acesso de um agente já conectado. Causa provável: O Cogram não tem uma tela de desconexão por agente. Correção: Remova o conector no aplicativo de IA que o mantém. Para interromper todos os agentes conectados da organização de uma vez, desative o acesso MCP em Configurações da organização → Integrações.

Próximos passos

• Conectando aplicativos de IA — as etapas de conexão voltadas ao usuário.
• API Cogram — a API REST, para integrações sistema a sistema que precisam gravar dados.
• Licenciamento — quais módulos sua organização está licenciada para usar.
• Visibilidade de ativos — como funciona a visibilidade em nível de registro.
• Agente — o agente integrado do próprio Cogram, que não requer configuração.

Dúvidas? Envie um e-mail para support@cogram.com ou use o menu Ajuda no aplicativo.

---

Instruções do agente

Esta documentação é publicada com GitBook. GitBook é a plataforma de documentação projetada para que tanto humanos quanto agentes de IA possam ler, navegar e raciocinar sobre conteúdo técnico de forma eficaz. Saiba mais em gitbook.com.

Consultando esta documentação

Se você precisar de informações adicionais que não estão diretamente disponíveis nesta página, você pode consultar a documentação dinamicamente fazendo uma pergunta.

Execute uma solicitação HTTP GET na URL da página atual com o parâmetro de consulta ask e o parâmetro de consulta opcional goal:

GET https://docs.cogram.com/integrations/mcp-server.md?ask=<question>&goal=<endgoal>

ask é a pergunta imediata: deve ser específica, autocontida e escrita em linguagem natural. goal é opcional e descreve o objetivo final mais amplo que você está tentando alcançar em nome do usuário. O GitBook o utiliza para adaptar a resposta ao que for mais útil para esse objetivo.

A resposta conterá uma resposta direta à pergunta, além de trechos e fontes relevantes da documentação.

Use este mecanismo quando a resposta não estiver explicitamente presente na página atual, quando você precisar de esclarecimentos ou contexto adicional, ou quando quiser recuperar seções relacionadas da documentação.