Documentação

Entenda e conecte o gateway OnixMCP.

O OnixMCP expõe apenas 6 meta-tools (ONIX_SEARCH_TOOLS, ONIX_GET_TOOL_SCHEMAS, ONIX_EXECUTE_TOOLS, ONIX_MANAGE_CONNECTIONS, ONIX_LIST_TOOLKITS, ONIX_WORKBENCH) ao seu cliente MCP. Por trás delas, o servidor descobre toolkits em runtime, gerencia conexões OAuth por usuário e executa lotes de chamadas em paralelo — sem que o modelo precise carregar centenas de definições de tools no contexto.

Visão geral

O OnixMCP é um gateway MCP de orquestração. Em vez de expor centenas de tools individuais (uma por ação de cada integração), ele expõe apenas 6 meta-tools ao seu modelo. Elas cuidam de descobrir, autenticar e executar todo o resto — GitHub, Notion, Microsoft 365, Google Workspace, WhatsApp, Protheus e outras integrações — sem sobrecarregar o contexto do agente com definições de tools que ele talvez nunca use.

Não existe mais divisão por “áreas” ou “rotas” do servidor: é um único gateway, com o mesmo conjunto completo de meta-tools e toolkits disponível em qualquer URL de conexão. Toolkits são descobertos dinamicamente em runtime, não fixados em código no cliente.

Arquitetura em 6 meta-tools

Toda a orquestração acontece por trás dessas 6 tools públicas. O modelo nunca vê qual provedor de terceiros está por trás de uma integração — apenas o resultado.

ONIX_SEARCH_TOOLS

Busca que pensa

Busca semântica entre integrações externas e toolkits locais, com paginação — o modelo encontra a ferramenta certa sem carregar o catálogo inteiro.

ONIX_GET_TOOL_SCHEMAS

Schemas sob demanda

Devolve o schema completo de uma ou mais tools pelo slug, só quando o modelo realmente precisa validar os parâmetros de uma chamada.

ONIX_EXECUTE_TOOLS

Execução em lote

Executa até 50 chamadas em paralelo, com timeout configurável, retry automático para leituras e erros estruturados (AUTH_REQUIRED, VALIDATION_ERROR, RATE_LIMITED…).

ONIX_MANAGE_CONNECTIONS

Conexões que aprendem

Gerencia OAuth de integrações externas e conexões de toolkits locais por usuário — sem segredos no prompt, nunca.

ONIX_LIST_TOOLKITS

Catálogo vivo

Lista toolkits disponíveis com status de conexão em tempo real, descobertos dinamicamente — sem hardcode de integrações no cliente.

ONIX_WORKBENCH

Workbench para payloads grandes

Leitura paginada de respostas truncadas — o modelo nunca perde dados por limite de contexto, mesmo em respostas gigantes de APIs de terceiros.

· Sessão única por usuário — cada conta mantém uma sessão MCP ativa (com TTL configurável), evitando múltiplas conexões concorrentes.
· Execução em lote paralela — até 50 chamadas por requisição, com timeout por chamada e retry automático apenas para operações de leitura.
· Erros estruturados — códigos como AUTH_REQUIRED, RATE_LIMITED ou VALIDATION_ERROR dizem ao agente exatamente qual é o próximo passo.
· Auditoria por chamada — cada chamada individual dentro de um lote é registrada, facilitando diagnosticar falhas específicas.

Fluxo recomendado do agente

Buscar

ONIX_SEARCH_TOOLS

O modelo descreve a intenção e recebe as tools mais relevantes, já rankeadas.

Conectar

ONIX_MANAGE_CONNECTIONS

Se faltar autorização, o gateway devolve AUTH_REQUIRED e o link de conexão OAuth.

Executar

ONIX_EXECUTE_TOOLS

Chamadas em lote, em paralelo, com retry seguro só para operações de leitura.

Explorar

ONIX_WORKBENCH

Se a resposta for grande, o modelo pagina o payload sem perder contexto.

Conectar um cliente MCP

Qualquer cliente MCP se conecta com dois dados: a URL pública do gateway e o token JWT da sua conta. Você encontra os dois reais (já preenchidos) em Dashboard → Conectar. Abaixo, um exemplo com valores de placeholder:

Settings → MCP → Add new MCP Server, ou edite mcp.json diretamente.

{
  "mcpServers": {
    "onixmcp": {
      "url": "https://api.onixmcp.com",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_JWT_AQUI"
      }
    }
  }
}

Nunca compartilhe seu token em canais públicos ou prompts — quem o possuir pode chamar o gateway em seu nome.

Segurança & privacidade

· Autenticação por usuário via JWT — sem chaves de API de terceiros embutidas no seu cliente ou prompt.
· O gateway nunca expõe ao cliente qual provedor de terceiros está por trás de uma integração — nem em respostas, nem em mensagens de erro.
· Conexões OAuth ficam vinculadas à sua conta e podem ser geridas a qualquer momento pelas próprias meta-tools de conexão.
· Erros de autenticação invalidam a sessão automaticamente, evitando reuso de tokens expirados ou revogados.

Perguntas frequentes

Qual URL devo usar para conectar meu cliente MCP?

Use apenas a URL raiz do gateway (ex.: https://seu-servidor.com) com o token JWT no cabeçalho Authorization. Não é necessário escolher caminhos como /tec ou /base — o OnixMCP expõe um único gateway com as 6 meta-tools ONIX_* e descoberta dinâmica de integrações.

O modelo vê todas as integrações de uma vez?

Não — ele busca sob demanda com ONIX_SEARCH_TOOLS e só recebe o schema completo das tools relevantes com ONIX_GET_TOOL_SCHEMAS, o que mantém o contexto pequeno mesmo com dezenas de integrações disponíveis.

O que acontece se a resposta de uma integração for muito grande?

O gateway trunca o payload e devolve uma referência; o modelo usa ONIX_WORKBENCH para paginar o conteúdo completo sem perder dados.

Como funciona o Playground?

O Playground do dashboard cria uma sessão de chat com o mesmo gateway, permitindo testar prompts e ver os logs de execução das tools antes de integrar o cliente final.

Pronto para conectar o seu agente com dados reais da sua conta?

Ir para Conectar