Omniscope

Crie e execute fluxos de dados, análises, relatórios e painéis. Inspecione e verifique cada etapa.

Ver em visokio.com

Servidor MCP hospedado

npx add-mcp 'https://omniscope.visokio.com/_api_/v1/cloudmcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

[!with-close] With-close

Conecte o Codex, o Claude Code ou o OpenCode a um projeto Omniscope, ou a uma pasta inteira de projetos, e deixe o agente construir diretamente nele. Ele pode preparar fontes de dados, adicionar e conectar blocos, executar o workflow, criar um Relatório, inspecionar os resultados e corrigir o que deu errado.

O resultado é um projeto Omniscope normal. Você pode abri-lo, inspecionar o workflow, alterar qualquer bloco e executá-lo novamente.
O trabalho permanece visível e editável no Omniscope, em vez de desaparecer em código gerado que você teria que fazer engenharia reversa.

Como exemplo, construímos um aplicativo funcional de Customer Success dessa forma em uma única sessão do Codex. O projeto finalizado é público, e Omniscope como ferramenta para agentes de IA explica como essa abordagem se encaixa junto aos recursos de IA que rodam dentro do Omniscope.

Este artigo cobre a configuração: os endpoints MCP, a chave de autenticação e a configuração necessária para cada cliente.

Se você tem uma conta Omniscope Cloud, há um caminho mais rápido: conecte seu agente ao Omniscope Cloud via MCP e faça login com sua conta habitual, sem precisar criar chave ou configurar servidor. Seu agente então trabalha diretamente na sua pasta Cloud. Veja Usar o Omniscope Cloud a partir do Claude ou ChatGPT.

Antes de começar

Disponível na versão Preview verificada mais recente. Você precisará de:

  • Uma licença Enterprise que inclua automação. MCP e a API REST são cobertos pelos recursos de Automação
  • Workflow Ninja & MCP Server ativado. Admin → Labs → Recursos experimentais → marque Workflow Ninja & MCP Server e salve. Depois, em Admin → Avançado → API, ative Enable Ninja Automation API (ferramentas MCP e REST).
  • Somente para o endpoint de pasta: em Admin → Avançado → API, ative também Enable folder MCP. Ele fica desativado por padrão porque alcança todos os projetos de uma pasta, em vez de apenas um. Para permitir que o agente liste, crie e envie arquivos para projetos, ative também Enable Project API. Nenhum desses requer reinicialização.

Um projeto, ou uma pasta inteira

Há duas maneiras de conectar um agente, e ambas oferecem as mesmas ferramentas de workflow.

Um projeto

Acrescente /api/mcp ao endereço do projeto:

https://your-server.example.com/Folder/Project.iox /api/mcp

A chave alcança aquele projeto e nenhum outro.

As mesmas ferramentas também estão disponíveis via REST no endereço do projeto, para chamadores que preferem não usar MCP:

RotaFinalidade
…/api/mcpMCP via JSON-RPC. É a isso que um agente se conecta.
…/api/toolsREST. POST {"list": true} para descoberta, ou um lote de chamadas.
…/api/tools/<tool>REST, uma ferramenta por URL. O corpo são os argumentos da ferramenta.

Uma pasta inteira

Acrescente /api/v1/mcp ao endereço de uma pasta, ou à raiz do servidor para o servidor inteiro:

https://your-server.example.com/Folder /api/v1/mcp

Uma única conexão alcança todos os projetos nessa pasta e em suas subpastas que a chave possa usar. O agente nomeia o projeto em cada chamada, como um caminho relativo à pasta (por exemplo, Team/Sales.iox), e também pode listar projetos, criar um projeto a partir de um modelo e enviar arquivos de dados.

Prefira a pasta mais restrita que atenda à necessidade: uma chave na raiz do servidor alcança todos os projetos que seu grupo possa usar.

A descoberta faz parte do protocolo, então você não precisa informar ao agente o que o Omniscope pode fazer. Ele pergunta e recebe a lista atual de ferramentas de volta.

Criar uma chave para o agente

Uma chave de API é uma credencial de longa duração para uma máquina. Não é um login: apresentá-la não conectará o agente à interface do Omniscope, e ela só é aceita nas rotas programáticas acima.

Abra a lista de projetos, clique no seu avatar no canto superior direito, escolha Editar permissão e percorra o diálogo.

Crie um grupo para seus agentes. Em Grupos, clique em Adicionar grupo e dê um nome que você reconhecerá depois — MCP serve.

Dê a permissão de API. Defina Permissões do grupo como Personalizado, clique em Configurar e defina Acesso total ao projeto via APIs como Sim.

Essa permissão abre a porta e nada mais. Como diz a dica de ferramenta, ela não concede nada por si só: se o agente pode ler, ou também escrever, ainda é decidido por Visualizador de projeto e Editor de projeto no mesmo painel. Para um agente que vai criar um projeto, dê Editor de projeto. Para um que deve apenas ler e relatar, deixe como visualizador.

Adicione a chave. Em Autenticação do grupo, clique em Adicionar mecanismo de autenticação e escolha Chaves de API.

Clique em Adicionar. O Omniscope gera uma chave no seu navegador, aplica hash e envia apenas o hash ao servidor. Ela se parece com isto:

omsk_ADYMeQQmn2A_ro1FVx-IO4DrdqrLfe_nCsw68nlMpKs

Copie a chave antes de fechar o diálogo. Ela é armazenada como um hash BCrypt, então ninguém — nem você, nem nós — pode recuperá-la depois. Se você a perder, gere uma nova, o que invalida a antiga.

Depois, clique em Salvar. O diálogo não permitirá salvar uma chave que não foi devidamente submetida a hash, então um salvamento bem-sucedido significa que a credencial é válida.

Para rotacionar depois, use o botão de regenerar na linha. A identidade da chave permanece a mesma, então o log de acesso ainda atribui atividades passadas a ela, enquanto a credencial em si muda e o valor antigo para de funcionar imediatamente.

Para o endpoint de pasta, configure o grupo e a chave na pasta à qual você se conectará: abra essa pasta na lista de projetos e depois avatar → Editar permissão. Dê ao grupo Acesso total ao projeto via APIs, além de Listar diretório para que o agente encontre projetos. Adicione Gerenciamento de arquivos se ele deve criar projetos, e Editor de projeto se deve alterá-los.

Uma subpasta com permissões próprias é uma área separada: a chave precisa de um grupo lá também, ou o agente não conseguirá alcançar projetos dentro dela.

Configurar o cliente

Para o endpoint de pasta, use a URL da pasta em qualquer uma das configurações abaixo. Uma entrada cobre todos os projetos da pasta.

Codex

Adicione uma tabela [mcp_servers.…] ao ~/.codex/config.toml, ou use .codex/config.toml dentro de um projeto:

[mcp_servers.omniscope] url = "https://your-server.example.com/Folder/Project.iox/api/mcp" bearer_token_env_var = "OMNISCOPE_MCP_TOKEN"

Defina OMNISCOPE_MCP_TOKEN como a chave no seu ambiente. O Codex a envia como o cabeçalho Authorization para você, e a chave fica fora do arquivo de configuração e fora do controle de versão.

A extensão do IDE expõe as mesmas configurações no menu de engrenagem → Servidores MCP.

Se preferir definir o cabeçalho diretamente, http_headers aceita valores estáticos e env_http_headers os lê do ambiente:

[mcp_servers.omniscope] url = "https://your-server.example.com/Folder/Project.iox/api/mcp" env_http_headers = { Authorization = "OMNISCOPE_MCP_AUTH" }

Execute codex mcp list para verificar se foi registrado, e /mcp dentro do TUI do Codex para ver se está conectado.

Claude Code

Um único comando:

claude mcp add --transport http omniscope https://your-server.example.com/Folder/Project.iox/api/mcp --header "Authorization: Bearer omsk_…"

Se você configurar como JSON — em .mcp.json ou ~/.claude.json — a entrada precisa de "type": "http". Um url sem type é tratado como erro de configuração, em vez de ser adivinhado.

Claude Desktop

O Claude Desktop se conecta a servidores MCP remotos por meio de Personalizar → Conectores → Adicionar conector personalizado, que aceita a URL do servidor e, nas configurações avançadas, um Client ID e Secret OAuth. Não há campo para cabeçalho estático, então uma chave de API do Omniscope não pode ser usada aqui.

Use Codex ou Claude Code para o caminho da chave de API. Se você precisar especificamente do Claude Desktop, autentique-se pela integração OpenID Connect do Omniscope, que é OAuth e se encaixa no modelo de conector.

OpenCode

Adicione uma entrada em mcp em ~/.config/opencode/opencode.json, ou em opencode.json na raiz de um projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "omniscope": {
      "type": "remote",
      "url": "https://your-server.example.com/Folder/Project.iox/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:OMNISCOPE_MCP_TOKEN}"
      },
      "timeout": 30000
    }
  }
}

Defina OMNISCOPE_MCP_TOKEN como a chave no seu ambiente. O OpenCode preenche {env:…} ao carregar a configuração, então a chave fica fora do arquivo e fora do controle de versão. Você pode colocar a chave omsk_… diretamente no cabeçalho, mas apenas em uma configuração que você não faça commit.

"oauth": false é importante. Sem isso, o OpenCode tenta iniciar um login OAuth quando um servidor pede autenticação, e uma chave de API do Omniscope não é OAuth. timeout é quanto tempo o OpenCode espera pela lista de ferramentas. O padrão é 5 segundos, o que pode ser curto demais para o conjunto completo de ferramentas do Omniscope.

Execute opencode mcp list para verificar se registrou e conectou.

Diga ao agente o que você quer, não como clicar

Uma vez conectado, o agente descobre as ferramentas sozinho. Você dá a ele um objetivo:

Conecte-se ao projeto Omniscope no servidor MCP. Veja o que já está no workflow, depois carregue customers.csv e renewals.csv, junte-os pelo ID da conta, descubra quais renovações estão em risco nos próximos 90 dias e crie um Relatório com uma visão resumida e uma tabela que eu possa filtrar por proprietário. Execute o workflow e verifique a saída antes de me dizer que terminou.

Poder dizer verifique a saída é a parte que muda como isso se sente. O agente executa o workflow pelo mesmo caminho de execução que a interface usa, lê o resultado e se corrige.

Em nossos experimentos, foi além: onde algo ainda não estava exposto como ferramenta via MCP ou API, o Codex dirigiu a interface do Omniscope como uma pessoa faria.

Verificar se funciona

Pergunte ao seu agente "liste meus projetos Omniscope".

  • 404 em uma URL de pasta: Enable Ninja Automation API ou Enable folder MCP está desativado, ou a URL não termina em /api/v1/mcp.
  • 400: Workflow Ninja & MCP Server está desativado em Admin → Labs.
  • 401: a chave está ausente, errada ou não está em um grupo na pasta à qual você se conecta, ou na pasta que contém o projeto.
  • 403: o grupo não tem Acesso total ao projeto via APIs, ou a licença não inclui automação.
  • "Nenhum projeto nesse caminho": o projeto não existe, está fora da pasta ou a chave não pode usá-lo.

Executar contra o Omniscope na sua própria máquina

As orientações acima se aplicam principalmente quando um agente se conecta ao Omniscope por uma rede. Quando você executa o Omniscope na sua máquina e se conecta a ele a partir da mesma máquina, a configuração é intencionalmente um pouco diferente.

Um projeto local tem um endereço como:

http://127.0.0.1:24679/Project.iox/api/mcp

Uma pasta local, ou todo o servidor local:

http://127.0.0.1:24679/\_api\_/v1/mcp

http://127.0.0.1:24679/Folder/\_api\_/v1/mcp

Esta é a maneira mais simples de começar com MCP localmente.

Por padrão, solicitações de localhost usam a Experiência de desktop local do Omniscope. Esse modo é projetado para aplicativos executados no seu próprio computador e dá a eles o mesmo acesso amplo a projetos e pastas que você esperaria ao usar o Omniscope como aplicativo de desktop.

Como resultado, ao conectar por localhost:

  • Uma chave de API não é necessária nem verificada, mesmo que uma tenha sido configurada.
  • A configuração Acesso total ao projeto via APIs não restringe a conexão local, porque a Experiência de desktop local tem precedência.

Esse é um comportamento intencional para uso local em desktop. Ele permite que o Omniscope funcione convenientemente com outros aplicativos executados na mesma máquina, sem exigir autenticação adicional para cada solicitação local.

Se preferir usar o Omniscope como um serviço acessível por rede, você pode ativar o servidor web externo e conectar-se pelo endereço associado ao adaptador de rede da máquina. Nessa configuração, as configurações normais de autenticação e permissão de API se aplicam, incluindo chaves de API e controles de acesso a projetos.

Para implantações de servidor ou estilo produção, onde você quer que todas as conexões sigam essas regras de autenticação e permissão de rede, desative Experiência de desktop local em Admin → Servidor web → Rede.

Em resumo, você pode escolher a configuração que atende ao seu caso de uso:

  • Uso local em desktop: acesso conveniente para aplicativos executados na sua própria máquina, com permissões locais completas.
  • Uso externo/rede: acesso pelo servidor web externo, com chaves de API e permissões configuradas aplicadas.

Se você não quiser que o MCP esteja disponível de forma alguma, desative Workflow Ninja & MCP Server em Admin → Labs. Isso desativa o endpoint MCP tanto para conexões locais quanto remotas.

Para manter os endpoints de projeto, mas bloquear o acesso a pastas, deixe Enable folder MCP desativado em Admin → Avançado → API.

0 de 0