Skip to content
Instalar no VS Code

Use o servidor MCP do Oracle CPQ com Claude Code, Cursor e GitHub Copilot

Conecte seu agente de IA ao servidor MCP Oracle hospedado do CPQ DevKit™ para que ele leia funções BML, tabelas de dados, configuração de commerce e muito mais do seu site Oracle CPQ.

Nesta página

O servidor MCP Oracle do CPQ DevKit™ é um servidor Model Context Protocol hospedado em https://app.cpqdevkit.com/mcp/oracle. Ele oferece a um agente de IA ferramentas para consultar seu site Oracle CPQ: funções da biblioteca util BML, tabelas de dados, processos e documentos de commerce, peças, arquivos, usuários, pacotes de migração e muito mais. Este guia cobre o Claude Code, o Cursor e o GitHub Copilot no VS Code.

Antes de começar

  • Um site Oracle CPQ Cloud com acesso à API REST (BigMachines standalone ou Fusion Applications). As ferramentas da biblioteca BML exigem REST v19.
  • Um usuário do Oracle CPQ que possa ler, pela API REST, os dados que você quer que o agente veja. Usar um usuário de integração dedicado é uma boa ideia.
  • Uma conta gratuita do CPQ DevKit™. Você pode criá-la pela extensão Oracle ou em app.cpqdevkit.com.
  • A ferramenta de IA que você quer usar: VS Code 1.109 ou posterior com GitHub Copilot, Claude Code ou Cursor.

Caminho mais simples: VS Code

Se você trabalha no VS Code, não precisa configurar nada manualmente:

  1. Instale o CPQ DevKit™ for Oracle pelo VS Code Marketplace.
  2. Execute Sign In na Paleta de Comandos. Ao entrar, sua chave de API do CPQ DevKit™ é criada e guardada no armazenamento de segredos do VS Code.
  3. Configure seu projeto e adicione seu ambiente Oracle CPQ. A extensão repassa ao servidor MCP o endereço do site e as credenciais do ambiente ativo.

Depois disso, o VS Code lista o servidor MCP CPQ DevKit™ for Oracle para o GitHub Copilot. O servidor usa o ambiente que está ativo no momento em que ele inicia, por isso reinicie o servidor depois de trocar de ambiente.

Essa configuração automática vale para o VS Code. O Claude Code e o Cursor mantêm suas próprias listas de servidores MCP, então adicione o servidor neles uma vez, como mostrado abaixo.

Obter uma chave de API

As configurações manuais abaixo precisam de uma chave de API do CPQ DevKit™:

  1. Entre em app.cpqdevkit.com.
  2. Crie uma chave de API e copie-a. A chave completa aparece só uma vez, então guarde-a em um lugar seguro, como o seu gerenciador de senhas.
  3. Mantenha a chave fora do controle de versão. Os exemplos abaixo a leem de uma variável de ambiente.

O que o servidor precisa

O servidor lê estes cabeçalhos HTTP:

CabeçalhoValor
X-API-KeySua chave de API do CPQ DevKit™
X-Oracle-CPQ-Base-URLO endereço do seu site, por exemplo https://yoursite.bigmachines.com
X-Oracle-CPQ-UsernameNome de usuário do Oracle CPQ (junto com X-Oracle-CPQ-Password)
X-Oracle-CPQ-PasswordSenha do Oracle CPQ
X-Oracle-CPQ-Access-TokenOpcional: um token de acesso OAuth do Oracle CPQ, em vez de nome de usuário e senha
X-Oracle-CPQ-Rest-Base-PathOpcional: o caminho base da REST, se o seu site não usa o padrão
X-Oracle-CPQ-Api-VersionOpcional: versão da API REST, v19 por padrão

O servidor usa o endereço do site e as credenciais enviados em cada requisição para chamar o seu site Oracle CPQ naquela requisição. Os exemplos abaixo usam estas variáveis de ambiente, que você define no perfil do seu shell, reiniciando em seguida o editor ou o terminal:

export CPQDEVKIT_API_KEY="cpqdk_..."
export ORACLE_CPQ_BASE_URL="https://yoursite.bigmachines.com"
export ORACLE_CPQ_USERNAME="integration.user"
export ORACLE_CPQ_PASSWORD="..."

Claude Code

Adicione o servidor com um único comando. Execute-o na pasta do seu projeto:

claude mcp add --transport http cpq-devkit-oracle https://app.cpqdevkit.com/mcp/oracle \
  --header "X-API-Key: $CPQDEVKIT_API_KEY" \
  --header "X-Oracle-CPQ-Base-URL: $ORACLE_CPQ_BASE_URL" \
  --header "X-Oracle-CPQ-Username: $ORACLE_CPQ_USERNAME" \
  --header "X-Oracle-CPQ-Password: $ORACLE_CPQ_PASSWORD"

O seu shell preenche os valores, e o Claude Code os salva nas próprias configurações, apenas para este projeto. Adicione --scope user para usar o servidor em todos os projetos.

Para compartilhar a configuração com a sua equipe sem compartilhar segredos, adicione em vez disso um arquivo .mcp.json na raiz do projeto. O Claude Code lê os valores das variáveis de ambiente de cada pessoa:

{
  "mcpServers": {
    "cpq-devkit-oracle": {
      "type": "http",
      "url": "https://app.cpqdevkit.com/mcp/oracle",
      "headers": {
        "X-API-Key": "${CPQDEVKIT_API_KEY}",
        "X-Oracle-CPQ-Base-URL": "${ORACLE_CPQ_BASE_URL}",
        "X-Oracle-CPQ-Username": "${ORACLE_CPQ_USERNAME}",
        "X-Oracle-CPQ-Password": "${ORACLE_CPQ_PASSWORD}"
      }
    }
  }
}

Execute claude mcp list para verificar se o servidor está conectado, ou digite /mcp em uma sessão do Claude Code. Na primeira vez, o Claude Code pede que você aprove os servidores definidos no .mcp.json do projeto.

Cursor

Crie .cursor/mcp.json no seu projeto, ou ~/.cursor/mcp.json na sua pasta pessoal para usar o servidor em todos os projetos:

{
  "mcpServers": {
    "cpq-devkit-oracle": {
      "url": "https://app.cpqdevkit.com/mcp/oracle",
      "headers": {
        "X-API-Key": "${env:CPQDEVKIT_API_KEY}",
        "X-Oracle-CPQ-Base-URL": "${env:ORACLE_CPQ_BASE_URL}",
        "X-Oracle-CPQ-Username": "${env:ORACLE_CPQ_USERNAME}",
        "X-Oracle-CPQ-Password": "${env:ORACLE_CPQ_PASSWORD}"
      }
    }
  }
}

O Cursor preenche ${env:…} a partir do seu ambiente, então defina as variáveis no perfil do shell e reinicie o Cursor. Depois, abra as Cursor Settings, encontre a seção MCP e confira se cpq-devkit-oracle mostra suas ferramentas.

GitHub Copilot no VS Code

A maioria dos usuários do VS Code não precisa desta seção: a extensão configura o servidor para você, como descrito em "Caminho mais simples: VS Code" acima. Use uma configuração manual se você não quiser instalar a extensão, ou para se conectar a um site diferente do ambiente ativo na extensão.

Crie .mcp.json na raiz do seu workspace:

{
  "mcpServers": {
    "cpq-devkit-oracle": {
      "type": "http",
      "url": "https://app.cpqdevkit.com/mcp/oracle",
      "headers": {
        "X-API-Key": "${CPQDEVKIT_API_KEY}",
        "X-Oracle-CPQ-Base-URL": "${ORACLE_CPQ_BASE_URL}",
        "X-Oracle-CPQ-Username": "${ORACLE_CPQ_USERNAME}",
        "X-Oracle-CPQ-Password": "${ORACLE_CPQ_PASSWORD}"
      },
      "tools": ["*"]
    }
  }
}

Para uma configuração que valha para todos os workspaces, coloque a mesma entrada mcpServers em ~/.copilot/mcp-config.json. O VS Code lê os valores ${NAME} do ambiente em que ele foi iniciado, então defina as variáveis primeiro e só depois abra o VS Code. Configurações mais antigas usavam .vscode/mcp.json com uma chave servers; hoje o VS Code recomenda .mcp.json para novas configurações.

Para verificar o servidor, abra o seletor de ferramentas na visualização de Chat e confira se o servidor e as ferramentas dele estão selecionados.

Exemplos de prompts

Estes prompts usam ferramentas de leitura, que funcionam no plano Free:

  1. "Liste as tabelas de dados do meu site Oracle CPQ."
  2. "Mostre as linhas da tabela de dados PartPricing em que o número da peça contém SRV."
  3. "Quais catálogos de preços estão configurados no meu site?"

Estes prompts usam ferramentas de agente, que exigem o plano Pro:

  1. "Liste as funções da biblioteca util BML do meu site Oracle CPQ, agrupadas por pasta."
  2. "Busque a função util calculateDiscount e revise se ela tem consultas BMQL dentro de loops e chamadas a funções que não existem."

Troque os nomes de funções e tabelas por nomes do seu site. Para testar a conexão antes, peça ao agente para listar as suas tabelas de dados: se ele responder com tabelas do seu site, o servidor está conectado. No plano Pro, você também pode perguntar: "A qual site Oracle CPQ o servidor MCP do CPQ DevKit está conectado?" O agente responde com o endereço do site e o método de login, nunca com senhas ou tokens.

O que exige o Pro

As ferramentas de leitura, como as de tabelas de dados, peças, catálogos de preços, configuração de commerce e usuários, são gratuitas dentro de um limite mensal: 100 chamadas por mês no plano Free e 10.000 no Pro. Cada ferramenta que o seu agente executa conta como uma chamada; conectar e listar ferramentas não conta.

Estas ferramentas exigem o plano Pro:

  • Ferramentas de escrita: create_transaction, perform_action, bulk_transaction_actions, generate_document, create_migration_package, export_migration_package, copy_migration_package, version_migration_package, migrate_package, create_snapshot, revert_to_snapshot, rollback_migration, create_full_backup, create_full_snapshot
  • Ferramentas em massa: get_all_data_table_data, get_all_endpoint_data, get_openapi_spec, get_performance_logs, get_performance_log
  • Ferramentas de agente: describe_environment, list_bml_functions, get_bml_function, list_bml_folders, list_integrations, review_bml. Com elas, o seu agente consulta e revisa funções BML e descreve o site conectado.

No plano Free, o servidor responde a essas ferramentas com uma mensagem informando que o Pro é necessário, e nada é enviado ao seu site. As ferramentas de escrita alteram o seu site Oracle CPQ, então revise o que o agente pretende fazer antes de aprovar uma chamada.

Solução de problemas

  • "Please provide an API key": o cabeçalho X-API-Key está faltando. Verifique se a variável de ambiente está definida no ambiente a partir do qual o editor ou o terminal foi iniciado.
  • "Missing required Oracle CPQ headers": adicione X-Oracle-CPQ-Base-URL e, além dele, um nome de usuário e uma senha ou um token de acesso.
  • "The provided API key is invalid or expired": crie uma nova chave em app.cpqdevkit.com e atualize a sua variável de ambiente.
  • "Monthly usage limit reached": você já usou as chamadas deste mês previstas no seu plano.

Dúvidas ou problemas? Escreva para sales@cpqdevkit.com. Veja a política de privacidade para saber como tratamos os dados.