Pular para o conteúdo principal

Conecte seu editor ao servidor MCP

O servidor MCP da Cogneris coloca a plataforma Cogneris dentro do assistente de IA do seu editor de código. Depois de conectado, o assistente pesquisa a documentação da Cogneris, lê o contrato exato de qualquer rota da API, cria chaves de API e webhooks, treina classificadores e executa jobs de preenchimento — no seu tenant, com a mesma trilha de auditoria da API REST.

É um endpoint da plataforma que você já usa, não um segundo produto: cada chamada de ferramenta chega aos mesmos serviços da Cogneris que a API REST, com o mesmo tenant, a mesma medição de consumo e a mesma trilha de auditoria.

MCP da Cogneris: Cogneris no VS Code: MCP, chave de API, código Python e webhooks Assistir no YouTube

URL do servidor​

Uma URL por região de produção. Use a região do seu tenant — a mesma do host da API que você já chama (api-eu, ou api-us para um tenant nos Estados Unidos). Tenants novos são criados na Europa.

RegiãoURL do servidor MCP
Europa (padrão)https://mcp-eu.cogneris.ai/
Estados Unidoshttps://mcp-us.cogneris.ai/

O endpoint JSON-RPC é a raiz /. Não existe o subcaminho /mcp: um cliente configurado com ele recebe 404.

Gere um token de desenvolvedor​

O token de desenvolvedor é o caminho recomendado: uma credencial com escopos e validade que mantém o seu editor conectado por até 90 dias.

  1. Na plataforma Cogneris, abra Vision → MCP. A página mostra a URL do seu servidor, a configuração pronta para colar em cada editor e o gerador de tokens.
  2. Dê ao token um nome que diga onde ele é usado (por exemplo "VS Code — notebook").
  3. Escolha a validade de 30 ou 90 dias.
  4. Escolha os escopos. mcp.read e mcp.write vêm marcados. Adicione apikeys.manage e webhooks.manage só se o assistente for gerenciar chaves de API e webhooks.
  5. Copie o token. Ele aparece uma única vez — gere outro se perdê-lo.

Toda ação feita com o token fica registrada no seu usuário. Revogue-o na mesma página quando não precisar mais dele.

O token de desenvolvedor não é uma chave de API

O token conecta o seu editor ao servidor MCP. O código que você publica chama a API REST com uma chave de API — que o assistente pode criar para você.

Adicione o servidor ao seu editor​

Troque a URL pela da sua região.

Crie .vscode/mcp.json no seu projeto. O token é um campo de senha: o VS Code o pede uma vez, guarda no armazenamento seguro dele e nunca o grava no arquivo — por isso o arquivo pode ir para o repositório, e todo o time usa a mesma configuração.

.vscode/mcp.json
{
  "inputs": [
    {
      "id": "cogneris-token",
      "type": "promptString",
      "password": true,
      "description": "Cogneris developer token"
    }
  ],
  "servers": {
    "cogneris": {
      "type": "http",
      "url": "https://mcp-eu.cogneris.ai/",
      "headers": { "Authorization": "Bearer ${input:cogneris-token}" }
    }
  }
}

Depois abra o Copilot Chat, mude para o modo Agent e confira se as ferramentas da Cogneris estão habilitadas na lista de ferramentas. O comando MCP: List Servers mostra se o servidor está rodando.

Confira a conexão​

Pergunte ao assistente:

Com quem estou conectado na Cogneris?

Ele chama cogneris_whoami e responde com o seu tenant, usuário e e-mail, como você entrou, sandbox ou produção, os escopos concedidos e a URL base da API que o seu código deve chamar. Se isso funciona, o resto também funciona.

Login pelo navegador em vez de token​

Configure a URL sem o cabeçalho Authorization. O servidor responde à primeira chamada com 401 e um cabeçalho WWW-Authenticate que aponta para os metadados dele — o sinal que um cliente MCP usa para abrir no navegador a página de login da Cogneris da sua região (authorization code com PKCE; não há client secret na sua configuração).

  • A sessão dura 1 hora, um controle de segurança do login da Cogneris. Para ficar conectado por dias, use um token de desenvolvedor.
  • O login pelo navegador concede mcp.read e mcp.write. As ferramentas de chaves de API e webhooks precisam de um token de desenvolvedor com esses escopos.

Escopos​

Uma ferramenta cujo escopo a sua credencial não tem não aparece na lista, e se recusa a rodar se for chamada.

EscopoO que libera
mcp.readTodas as listagens e consultas: conta, consumo, documentação e referência da API, classificadores, templates e jobs de preenchimento, o catálogo de eventos de webhook.
mcp.writeCriar classificadores, adicionar amostras e treiná-los, registrar templates de preenchimento, enviar arquivos de origem e iniciar jobs de preenchimento.
apikeys.manageListar, criar e revogar chaves de API. Nunca é implícito em mcp.write.
webhooks.manageGerenciar endpoints e entregas de webhook. Nunca é implícito em mcp.write.

O que o assistente consegue fazer​

35 ferramentas em seis áreas. Você nunca as chama pelo nome — descreve o que quer e o assistente escolhe.

ÁreaFerramentasO que o assistente faz com elas
Conta e consumocogneris_whoami, cogneris_usage_summaryConfirma com quem a conexão age; mostra documentos, páginas e tokens de IA por dia e por tipo de documento.
Documentação e referência da APIcogneris_docs_search, cogneris_docs_get, cogneris_api_operations, cogneris_api_referencePesquisa esta documentação e lê o contrato exato de uma rota, com código pronto em Node, Python, C# e curl que lê a chave de COGNERIS_API_KEY.
Chaves de APIcogneris_apikeys_list, cogneris_apikeys_create, cogneris_apikeys_revokeCria chaves só com os escopos de que o seu código precisa — sandbox por padrão.
Webhookscogneris_webhooks_event_types, cogneris_webhooks_create, cogneris_webhooks_test, cogneris_webhooks_deliveries_list, cogneris_webhooks_deliveries_replay e outrasRegistra endpoints, devolve o segredo de assinatura uma vez com o código do receptor, envia entregas de teste, inspeciona e reenvia as que falharam.
Classificadorescogneris_classifiers_create, cogneris_classifiers_add_samples, cogneris_classifiers_train, cogneris_classifiers_status e outrasCria os seus próprios tipos de documento a partir de arquivos de amostra e os treina.
Preenchimento de PDFcogneris_templates_register, cogneris_sources_upload, cogneris_jobs_create, cogneris_artifacts_download e outrasCarimba dados extraídos num template de PDF e baixa o resultado.

O servidor também traz dois prompts prontos que o seu editor lista no menu de prompts (no VS Code, digite / no chat): Integrate the Cogneris API into this project e Create and train a Cogneris classifier.

Classificadores não são templates de preenchimento

Classificadores são os seus próprios tipos de documento — os que o app da Cogneris mostra como templates. Templates de preenchimento são layouts de PDF em que um job de preenchimento carimba dados. Quando você pergunta "quais templates eu tenho?", a resposta que você quer vem dos classificadores.

Antes de deixar um agente no comando​

  • Chaves de API são de sandbox por padrão. Uma chave de produção só é criada quando você confirma explicitamente. Chaves criadas pelo editor nunca recebem apikeys.manage, mcp.read ou mcp.write.
  • Segredos aparecem uma única vez. Uma nova chave de API, segredo de assinatura de webhook ou segredo rotacionado aparece numa única resposta. O assistente é instruído a gravá-lo no seu .env ignorado pelo git e nunca repeti-lo.
  • Jobs de preenchimento consomem créditos. Um agente percorrendo uma pasta gasta orçamento de verdade — limite isso no prompt e também no teto de custo do tenant.
  • Criar não é idempotente. Cada chamada de criação gera um registro novo; uma chamada repetida é uma duplicata.
  • Uploads limitados a 10 MB decodificados (cerca de 7,5 MB de arquivo). Arquivos maiores vão pelo upload da API REST.
  • URLs assinadas de download expiram em 5 minutos. Baixe o arquivo assim que receber a URL.

Solução de problemas​

SintomaCausa e correção
404 em todas as chamadasA URL tem um caminho como /mcp. Use a raiz: https://mcp-eu.cogneris.ai/.
401 UnauthorizedToken ausente, expirado ou revogado. Gere outro em Vision → MCP.
As ferramentas de chaves de API ou webhooks não aparecemO token não tem apikeys.manage ou webhooks.manage, ou você entrou pelo navegador. Gere um token com esses escopos.
406 Not Acceptable no seu próprio clienteEnvie Accept: application/json, text/event-stream.
O assistente escreve o código sem consultar a CognerisConfira se o chat está no modo Agent com as ferramentas da Cogneris habilitadas, e cite a Cogneris no prompt.

Próximos passos​