Conectar um Cliente MCP

O servidor MCP da Copera é acessível em um único endpoint Streamable HTTP. Aponte seu cliente de IA para ele, forneça um token bearer, e o catálogo de ferramentas aparece automaticamente.

Endpoint

Endpoint MCP	https://mcp.copera.ai/mcp
Transporte	Streamable HTTP (POST)
Header de autenticação	Authorization: Bearer cp_pat_… ou cp_oat_…

Transporte sem estado

O servidor roda em modo sem estado — não há sessões para retomar. Apenas POST /mcp é suportado; GET e DELETE retornam 405. Um health check está disponível em GET /health.

Você vai precisar de um token antes de conectar. A opção mais simples é um Personal Access Token (cp_pat_…) criado nas configurações do seu workspace Copera. Veja Autenticação para PATs vs. OAuth e como os escopos mapeiam para ferramentas.

Conectar um cliente

Criar um token

Gere um Personal Access Token (cp_pat_…) no seu workspace Copera e conceda a ele os escopos que seu agente precisa — por exemplo access_boards e access_docs. Trate-o como uma senha.

Adicionar o servidor ao seu cliente MCP

Configure seu cliente com a URL do endpoint e o token bearer. A maioria dos clientes aceita ou um bloco de configuração de servidor remoto ou um comando de bridge mcp-remote.

Servidor remoto (JSON)

{
  "mcpServers": {
    "copera": {
      "type": "http",
      "url": "https://mcp.copera.ai/mcp",
      "headers": {
        "Authorization": "Bearer cp_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

bridge mcp-remote

Para clientes que só suportam servidores stdio locais, faça uma ponte para o endpoint remoto com mcp-remote:

{
  "mcpServers": {
    "copera": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.copera.ai/mcp",
        "--header",
        "Authorization: Bearer cp_pat_YOUR_TOKEN_HERE"
      ]
    }
  }
}

Recarregar e verificar se as ferramentas aparecem

Reinicie ou recarregue o cliente MCP. O servidor copera deve conectar e expor suas ferramentas (list_boards, search, search_docs e assim por diante). Se o cliente suportar descoberta de ferramentas, você verá o catálogo completo descrito na Referência de ferramentas.

Faça sua primeira chamada

Peça ao modelo para chamar get_workspace_info — uma ferramenta somente-leitura que confirma se o token resolve para o workspace correto. A partir daí, list_boards → list_tables → list_rows percorre o fluxo de descoberta.

Conectores OAuth

Alguns clientes (como o Claude com conectores remotos) podem conectar via OAuth em vez de um token colado. Quando você adiciona a URL do servidor sem um bearer, o cliente recebe um 401 com um desafio WWW-Authenticate e inicia o fluxo OAuth automaticamente, gerando um token cp_oat_…. Veja Autenticação.

Testar com o MCP Inspector

O MCP Inspector é a forma mais rápida de confirmar a conectividade e explorar ferramentas manualmente antes de configurar um agente.

Inicie o Inspector

npx @modelcontextprotocol/inspector

Configure a conexão

Na interface do Inspector:

• Tipo de transporte: Streamable HTTP
• URL: https://mcp.copera.ai/mcp
• Autenticação: adicione um header Authorization com o valor Bearer cp_pat_YOUR_TOKEN_HERE

Liste e chame ferramentas

Conecte, abra a aba Tools e você deve ver todas as 37 ferramentas. Chame get_workspace_info para verificar o token, depois experimente list_boards para confirmar o acesso de leitura.

Mantenha os tokens em segredo

Qualquer pessoa que tenha seu token bearer pode agir como você dentro dos seus escopos. Não versione tokens no controle de código nem os cole em configurações compartilhadas. Rotacione um token imediatamente se ele vazar.

Resolução de problemas

Sintoma	Causa provável
401 Unauthorized	Token bearer ausente, malformado ou expirado. Reverifique o header Authorization: Bearer ….
403 Forbidden em uma ferramenta	O token não tem o escopo que essa ferramenta exige (ex.: access_docs para ferramentas de documentos). Veja Autenticação.
405 Method Not Allowed	O cliente enviou GET/DELETE para /mcp. O servidor é sem estado — use POST.
Ferramentas faltando no cliente	O servidor conectou, mas o cliente filtrou ferramentas, ou o token resolve para um workspace sem aqueles dados. Verifique com o Inspector.