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:
- Instale o CPQ DevKit™ for Oracle pelo VS Code Marketplace.
- 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.
- 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™:
- Entre em app.cpqdevkit.com.
- 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.
- 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çalho | Valor |
|---|---|
X-API-Key | Sua chave de API do CPQ DevKit™ |
X-Oracle-CPQ-Base-URL | O endereço do seu site, por exemplo https://yoursite.bigmachines.com |
X-Oracle-CPQ-Username | Nome de usuário do Oracle CPQ (junto com X-Oracle-CPQ-Password) |
X-Oracle-CPQ-Password | Senha do Oracle CPQ |
X-Oracle-CPQ-Access-Token | Opcional: um token de acesso OAuth do Oracle CPQ, em vez de nome de usuário e senha |
X-Oracle-CPQ-Rest-Base-Path | Opcional: o caminho base da REST, se o seu site não usa o padrão |
X-Oracle-CPQ-Api-Version | Opcional: 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:
- "Liste as tabelas de dados do meu site Oracle CPQ."
- "Mostre as linhas da tabela de dados
PartPricingem que o número da peça contémSRV." - "Quais catálogos de preços estão configurados no meu site?"
Estes prompts usam ferramentas de agente, que exigem o plano Pro:
- "Liste as funções da biblioteca util BML do meu site Oracle CPQ, agrupadas por pasta."
- "Busque a função util
calculateDiscounte 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-Keyestá 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-URLe, 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.