Couchbase
oficialInteraja com os dados armazenados em clusters Couchbase usando linguagem natural.
O que você pode fazer com Couchbase MCP?
- Explorar dados do cluster — Listar buckets, escopos e coleções e, em seguida, inferir o esquema de uma coleção como
orders. - Executar consultas SQL++ — Executar consultas SQL++ somente de leitura em um bucket e escopo e explicar os planos de consulta.
- Inspecionar documentos — Buscar um documento por ID ou ler caminhos específicos de subdocumentos sem carregar o documento inteiro.
- Verificar a integridade do cluster — Informar a integridade do cluster, os serviços em execução e os diagnósticos de conexão.
- Analisar o desempenho das consultas — Encontrar consultas de execução mais longa, mais frequentes ou que não usam índices de cobertura.
- Consultas de busca e vetoriais — Executar consultas de busca de texto completo e de similaridade vetorial em índices configurados.
Documentação
Servidor MCP do Couchbase
O Couchbase MCP Server é um servidor MCP auto-hospedado que permite que agentes de IA se conectem e interajam com dados em servidores Couchbase (hospedados no Capella ou autogerenciados) ou no Operational Insights Enterprise. Ele oferece ferramentas em categorias como integridade do cluster, esquema de dados, consultas e muito mais — com controles de segurança por meio do modo somente leitura e da desativação granular de ferramentas. Ele oferece suporte aos transportes STDIO e Streamable HTTP, com recursos de OAuth.
O Couchbase MCP Server é distribuído como um pacote do Python Package Index (PyPI) e via Docker. O suporte empresarial ao Couchbase MCP Server está disponível mediante licenciamento do Couchbase AI Data Plane, que também dá direito ao uso e ao suporte empresarial do Couchbase Agent Memory e do Couchbase Agent Catalog.
Documentação completa: docs.couchbase.com/mcp-server
Sumário
- Por que usar o Couchbase MCP Server
- Escolher um servidor
- Servidor operacional
- Servidor Operational Insights
- Configuração comum
- Configuração do cliente
- Docker
- Solução de problemas
- Perguntas frequentes
- Contribuição
- Dados de uso, riscos de LLM e política de suporte
Por que usar o Couchbase MCP Server
- Seguro por padrão — as ferramentas de gravação não são carregadas e as consultas que modificam dados são bloqueadas, a menos que você defina
CB_MCP_READ_ONLY_MODE=false; ferramentas individuais também podem ser desativadas ou exigir confirmação do usuário. - Couchbase Server e Operational Insights — o servidor operacional se conecta ao Couchbase Capella ou a um cluster autogerenciado do Couchbase Server com a mesma configuração; o servidor Operational Insights se conecta a clusters autogerenciados do Operational Insights.
- Compatível com RBAC — os controles das ferramentas orientam o LLM; o controle de acesso baseado em função do usuário do Couchbase continua sendo o limite de segurança autoritativo.
- Transportes para produção — STDIO para clientes de desktop locais ou Streamable HTTP com OAuth 2.1 opcional (qualquer IdP que publique JWKS: Auth0, Okta, Keycloak, Entra, Cognito, …), verificações de integridade e registro de auditoria para implantações compartilhadas. O servidor operacional também pode executar vários workers para usar mais núcleos de CPU.
- Qualquer cliente MCP — testado com Claude Desktop, Cursor, Windsurf, VS Code e JetBrains AI Assistant/Junie.
Depois de se conectar, você pode fazer perguntas como:
- "Quais buckets, scopes e collections tenho, e qual é o esquema da collection
orders?" - "Encontre os 10 documentos mais recentes em
usersnos quaisstatus = 'active'." - "Quais são as 5 consultas mais lentas da última hora e alguma delas está sem um índice de cobertura?"
- "Este cluster está íntegro e quais serviços estão em execução?"
- "Insira um novo documento em
productscom estes campos: …" (requerCB_MCP_READ_ONLY_MODE=false)
Escolher um servidor
Este pacote inclui dois servidores MCP. Cada um é iniciado por seu próprio subcomando, conecta-se a um tipo diferente de cluster e tem suas próprias ferramentas. Escolha o que corresponde ao seu cluster, siga a seção correspondente para configuração e ferramentas e, em seguida, consulte Configuração comum para ver as definições compartilhadas. Para usar ambos, registre cada um como um servidor separado no cliente MCP.
| Servidor operacional | Servidor Operational Insights | |
|---|---|---|
| Use com | Um cluster Couchbase (Capella ou autogerenciado) | Um cluster autogerenciado do Operational Insights (não disponível no Capella) |
| Subcomando | operational (o padrão) | operational-insights |
| String de conexão | couchbase:// / couchbases:// | URL HTTP(S), por exemplo, http://localhost:8095 |
| Variáveis de credenciais | CB_CONNECTION_STRING, CB_USERNAME, … | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, … |
| Ferramentas | 52 — integridade do cluster, esquema, KV, SQL++, índices, pesquisa de texto completo e vetorial, desempenho de consultas | 13 — esquema, SQL++ (síncrono e assíncrono), índices, exportações |
| Porta HTTP padrão | 8000 | 8001 |
| Arquivo de log padrão | mcp_server.log | mcp_server_operational_insights.log |
Atualmente, o subcomando é opcional para o servidor operacional — um
couchbase-mcp-serversem argumentos o inicia —, mas especificá-lo mantém sua configuração inequívoca. As opções vêm depois do subcomando:couchbase-mcp-server operational --transport=http. Verifique a versão instalada comuvx couchbase-mcp-server --version.
Servidor operacional
O servidor operational se conecta a um cluster Couchbase no Capella ou a um Couchbase Server autogerenciado, usando o SDK Python couchbase.
Início rápido do servidor operacional
Você precisa de um cluster Couchbase em execução — o nível gratuito do Capella é a maneira mais rápida de obter um (você pode importar um conjunto de dados de exemplo) — e de um cliente MCP. Adicione uma destas configurações ao seu cliente (consulte Configuração do cliente para saber onde cada cliente a mantém). Se o cliente já tiver outros servidores, adicione couchbase ao objeto mcpServers existente.
Do PyPI com uvx (requer uv e Python 3.11+):
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Com Docker (requer apenas Docker):
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_CONNECTION_STRING=couchbases://connection-string",
"-e", "CB_USERNAME=username",
"-e", "CB_PASSWORD=password",
"couchbase/mcp-server:latest", "operational"
]
}
}
}
Do código-fonte
git clone https://github.com/couchbase/mcp-server-couchbase.git
{
"mcpServers": {
"couchbase": {
"command": "uv",
"args": [
"--directory", "path/to/cloned/repo/mcp-server-couchbase/",
"run", "src/mcp_server.py", "operational"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
path/to/cloned/repo/mcp-server-couchbase/ é o caminho para seu clone — mantenha a barra final. Depois de obter as atualizações, execute uv sync para atualizar as dependências.
Conexão e autenticação do servidor operacional
Use ou um nome de usuário e senha ou um certificado de cliente (mTLS). Se ambos estiverem definidos, o certificado será usado.
| Variável de ambiente | Argumento CLI | Descrição |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | String de conexão com o cluster. Obrigatório |
CB_USERNAME / CB_PASSWORD | --username / --password | Autenticação básica |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | Autenticação mTLS |
CB_CA_CERT_PATH | --ca-cert-path | Certificado raiz para um certificado de servidor autoassinado/não confiável (não necessário para o Capella) |
Exemplo de mTLS
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
"CB_CLIENT_KEY_PATH": "/path/to/client.key"
}
}
}
}
Ferramentas do servidor operacional
As ferramentas de gravação (marcadas com ✏️) não são carregadas enquanto o modo somente leitura estiver ativado, o que é o padrão. As ferramentas marcadas com 🖥️ são apenas para ambientes autogerenciados — elas usam endpoints REST administrativos que o Capella não expõe ou (discover_tool_input_values) fornecem apenas dados de referência para uma ferramenta que os utiliza —, portanto, exigem o Couchbase Server 7.6+ autogerenciado e não são registradas em conexões com o Capella.
Configuração e integridade do cluster
| Ferramenta | Descrição |
|---|---|
get_server_configuration_status | Status e configuração do servidor sem se conectar ao cluster: modo somente leitura, ferramentas desativadas/com confirmação obrigatória, OAuth, registro em log e contadores de auditoria |
test_cluster_connection | Verificar as credenciais do cluster conectando-se a ele |
get_cluster_health_and_services | Integridade do cluster e serviços em execução, com filtragem opcional por meio de service_types |
get_client_connectivity_report | Diagnósticos de conexão armazenados em cache pelo SDK, sem sondagem ativa da rede |
get_cluster_metrics 🖥️ | Estatísticas do cluster em um intervalo histórico (endpoint stats-range) |
get_cluster_tasks 🖥️ | Tarefas em execução no momento — rebalanceamento, compactação, XDCR, criação de índices. Requer ro_admin |
get_cluster_health_snapshot 🖥️ | Integridade por nó: topologia de serviços, associação, orquestrador e resumo de integridade. Requer ro_admin |
get_bucket_config 🖥️ | Configuração e estado atual de um bucket (ou de todos os buckets) — cotas, política de remoção, réplicas, durabilidade, armazenamento, compactação. Requer ro_admin |
get_cluster_system_events 🖥️ | Log de eventos do sistema (alterações de configuração, failovers, rebalances, reinicializações), limitado por intervalo com since_time. Requer Full Admin ou Cluster Admin |
discover_tool_input_values 🖥️ | Consultar valores de entrada exatos necessários para outras ferramentas (por exemplo, todos os nomes de métricas para get_cluster_metrics). Funciona offline |
Descoberta do modelo de dados e do esquema
| Ferramenta | Descrição |
|---|---|
get_buckets_in_cluster | Listar todos os buckets do cluster |
get_scopes_in_bucket | Listar todos os scopes de um bucket |
get_collections_in_scope | Listar todas as collections de um scope (requer o serviço Query) |
get_scopes_and_collections_in_bucket | Listar todos os scopes e collections de um bucket |
get_schema_for_collection | Inferir a estrutura de uma collection |
create_scope ✏️ | Criar um scope em um bucket (Server 7.6+ e Capella) |
create_collection ✏️ | Criar uma collection em um scope existente (Server 7.6+ e Capella) |
delete_scope ✏️ | Excluir um scope e todas as suas collections — permanente |
delete_collection ✏️ | Excluir uma collection e todos os seus documentos — permanente |
Operações com documentos (KV)
| Ferramenta | Descrição |
|---|---|
get_document_by_id | Obter um documento pelo ID |
lookup_subdocument | Ler caminhos específicos, verificar existência ou contar sem buscar o documento inteiro |
upsert_document_by_id ✏️ | Fazer upsert de um documento pelo ID |
insert_document_by_id ✏️ | Inserir um novo documento (falha se ele já existir) |
replace_document_by_id ✏️ | Substituir um documento existente (falha se ele não existir) |
delete_document_by_id ✏️ | Excluir um documento pelo ID |
mutate_subdocument ✏️ | Modificar caminhos em um documento existente (upsert, insert, replace, remove, operações com arrays, contadores) |
Consultas e indexação
| Ferramenta | Descrição |
|---|---|
run_sql_plus_plus_query | Executar uma consulta SQL++ com escopo definido para um bucket e um scope — use os nomes das collections diretamente (SELECT * FROM users). Instruções que modificam dados são bloqueadas no modo somente leitura |
explain_sql_plus_plus_query | Gerar e avaliar um plano EXPLAIN: metadados, plano extraído e constatações |
get_index_advisor_recommendations | Recomendações do Index Advisor para uma consulta SQL++ |
list_indexes | Listar índices com definições, filtráveis por bucket/scope/collection/nome; identifica índices vetoriais (is_vector, vector_type) |
get_index_stats 🖥️ | Tamanho, fragmentação, tráfego de varredura e atraso por índice e por nó — identifica pressão e índices não utilizados |
create_query_index ✏️ | Criar um índice GSI escalar, vetorial Hyperscale ou vetorial composto (index_type). Adiado por padrão — em seguida, execute build_index |
create_index ✏️ | Obsoleto — use create_query_index. Removido na versão 2.0 |
build_index ✏️ | Criar todos os índices adiados em uma collection |
drop_index ✏️ | Remover um índice GSI (escalar ou vetorial) |
Pesquisa de texto completo (FTS)
Requer Couchbase Server 7.6+ e o serviço Search. Há suporte tanto para índices no nível do scope quanto para índices no nível do cluster (legados): passe bucket_name e scope_name juntos para o nível do scope ou omita ambos.
| Ferramenta | Descrição |
|---|---|
list_search_indexes | Lista índices Search — no nível do cluster, por bucket ou por escopo |
get_search_index_definition | Definição completa de um índice Search (mapeamentos, analisadores, parâmetros do plano) |
run_search | Executa qualquer consulta FTS não vetorial a partir do corpo JSON bruto; explain=true retorna o plano de execução |
upsert_search_index ✏️ | Cria ou atualiza um índice Search, incluindo mapeamentos de campos vetoriais. As atualizações acionam uma reconstrução completa — passe o uuid atual para evitar sobrescrever alterações simultâneas |
drop_search_index ✏️ | Remove um índice Search — permanentemente |
Pesquisa vetorial
Ambas as ferramentas incorporam texto de consulta simples usando o modelo configurado em Provedores de incorporação. Disponível no Couchbase Server autogerenciado e no Capella.
| Ferramenta | Descrição |
|---|---|
run_vector_query | Pesquisa por similaridade em um índice vetorial GSI (Server 8.0+) via APPROX_VECTOR_DISTANCE(). O índice é escolhido automaticamente; oferece suporte a um pré-filtro SQL++ where e ao ajuste Hyperscale (num_probes, rerank, top_n_scan). Retorna documentos completos |
run_vector_search | Pesquisa vetorial do serviço Search (Server 7.6+) em um índice nomeado. scalar_query torna a pesquisa híbrida; prefilter restringe os candidatos primeiro. Retorna os campos armazenados no índice para cada resultado |
Análise de desempenho de consultas
| Ferramenta | Descrição |
|---|---|
get_longest_running_queries | Consultas de execução mais longa por tempo médio de serviço |
get_most_frequent_queries | Consultas executadas com maior frequência |
get_queries_with_largest_response_sizes | Consultas com os maiores tamanhos de resposta |
get_queries_with_large_result_count | Consultas com as maiores quantidades de resultados |
get_queries_using_primary_index | Consultas que usam um índice primário |
get_queries_not_using_covering_index | Consultas que não usam um índice de cobertura |
get_queries_not_selective | Consultas cujas varreduras — de índice secundário, índice primário ou sequenciais — retornam muito mais documentos do que o resultado final |
Integridade do serviço Query 🖥️
Estas ferramentas chamam a própria API REST administrativa do serviço Query em cada nó de consulta.
| Ferramenta | Descrição |
|---|---|
get_cluster_query_vitals | Integridade do mecanismo de consulta: taxa de solicitações, solicitações ativas/em fila, memória, GC, tempo de atividade. Requer ro_admin |
get_active_queries | Consultas em execução neste momento em todos os nós de consulta. Requer ro_admin |
delete_active_query ✏️ | Cancela uma consulta em andamento pelo ID da solicitação. Requer Full Admin ou Cluster Admin |
Ferramentas desativadas automaticamente no Capella
As ferramentas 🖥️ acessam o Couchbase por meio de endpoints REST administrativos que o Capella não expõe (a única exceção, discover_tool_input_values, é omitida porque atende apenas a uma ferramenta que precisa deles). Quando todos os hosts em CB_CONNECTION_STRING terminam em .cloud.couchbase.com, o servidor não as registra e as informa junto com suas próprias ferramentas desativadas em get_server_configuration_status e no log de inicialização. Ferramentas baseadas no SDK, como get_cluster_health_and_services e get_client_connectivity_report, continuam disponíveis.
| Ferramenta | Endpoint necessário |
|---|---|
get_cluster_metrics | REST de gerenciamento (/pools/default/stats/range) |
get_cluster_tasks | REST de gerenciamento (/pools/default/tasks) |
get_bucket_config | REST de gerenciamento (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | REST de gerenciamento, além de endpoints por nó |
get_cluster_system_events | REST de gerenciamento (/events) |
get_index_stats | REST do serviço Index (o /api/v1/stats de cada indexador) |
get_cluster_query_vitals | REST do serviço Query (/admin/vitals) |
get_active_queries | REST do serviço Query (/admin/active_requests) |
delete_active_query | REST do serviço Query (DELETE /admin/active_requests/{id}) |
discover_tool_input_values | Nenhum (funciona offline), mas atende apenas a get_cluster_metrics, que não existe no Capella |
Provedores de incorporação
run_vector_query e run_vector_search incorporam o texto da consulta usando o provedor definido em CB_MCP_EMBEDDING_MODEL_PROVIDER. Isso é opcional: sem essa configuração, o servidor inicia normalmente e ambas as ferramentas continuam registradas, mas chamá-las retorna um erro explicando o que configurar.
CB_MCP_EMBEDDING_MODEL_PROVIDER | Obrigatório | Opcional | Observações |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service. CB_MCP_EMBEDDING_MODEL_ENDPOINT é a URL própria da sua implantação (por exemplo, https://<id>.ai.couchbase.com) em AI Data Plane > Models do Capella |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | Defina o endpoint para usar um servidor local compatível com OpenAI (Ollama, vLLM, LM Studio) |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGION | Modelos de incorporação Amazon Titan (por exemplo, amazon.titan-embed-text-v2:0) — o provedor envia o formato de solicitação inputText do Titan, portanto outros modelos de incorporação do Bedrock, como Cohere Embed, ainda não são compatíveis. Omita as credenciais para usar a cadeia padrão da AWS. Requer o extra: pip install couchbase-mcp-server[bedrock-embeddings] |
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
"CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
"CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}
Todas as opções
Todas as variáveis de ambiente e flags CLI do servidor operational server
O servidor Operational Insights aceita as mesmas opções, exceto que tem suas próprias configurações de conexão e não possui opções CB_MCP_EMBEDDING_MODEL_*.
| Variável de ambiente | Argumento da CLI | Descrição | Padrão |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | String de conexão com o cluster Couchbase | Obrigatório |
CB_USERNAME | --username | Nome de usuário com acesso aos buckets necessários para autenticação básica | Obrigatório (ou Certificado e Chave do Cliente necessários para mTLS) |
CB_PASSWORD | --password | Senha para autenticação básica | Obrigatório (ou Certificado e Chave do Cliente necessários para mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Caminho para o arquivo de certificado do cliente para autenticação mTLS | Obrigatório se estiver usando mTLS (ou Nome de usuário e Senha obrigatórios) |
CB_CLIENT_KEY_PATH | --client-key-path | Caminho para o arquivo de chave do cliente para autenticação mTLS | Obrigatório se estiver usando mTLS (ou Nome de usuário e Senha obrigatórios) |
CB_CA_CERT_PATH | --ca-cert-path | Caminho para o certificado raiz do servidor para TLS, caso o servidor esteja configurado com um certificado autoassinado/não confiável. Isso não será necessário se você estiver se conectando ao Capella | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | Impede todas as modificações de dados (KV, Query, gerenciamento de escopos/coleções, gerenciamento de índices e gerenciamento de índices FTS). Quando ativado, as ferramentas de gravação não são carregadas. | true |
CB_MCP_TRANSPORT | --transport | Modo de transporte: stdio, http | stdio |
CB_MCP_HOST | --host | Host para o modo de transporte HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | Porta para o modo de transporte HTTP | 8000 |
CB_MCP_WORKERS | --workers | Número de processos de trabalho do servidor para o transporte http. Valores acima de 1 executam no modo HTTP sem estado (consulte Vários processos de trabalho) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | Processa cada solicitação HTTP sem estado por sessão. Só é considerado com http; não pode ser combinado com ferramentas que exigem confirmação (consulte Vários processos de trabalho) | true quando workers > 1; caso contrário, false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | Ferramentas a desativar (consulte Desativar ferramentas) | Nenhuma |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Ferramentas que exigem confirmação explícita do usuário antes da execução via elicitação MCP (consulte Exigir confirmação) | Nenhuma |
CB_MCP_LOG_LEVEL | --log-level | Nível de registro do servidor MCP: off, debug, info, warning, error (consulte Registro) | info |
CB_MCP_LOG_SINKS | --log-sinks | Destinos de registro separados por vírgulas: stderr, file ou ambos (consulte Registro) | stderr |
CB_MCP_LOG_FILE | --log-file | Caminho base para arquivos de registro por nível (usado somente quando o destino file está ativado) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | Tamanho máximo global em MB por arquivo de registro antes da rotação, herdado por cada nível, a menos que seja substituído. 0 — ou um valor que não possa ser usado, como um número negativo, nan ou inf — é inválido e usa o padrão, com um aviso na inicialização | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Obsoleto — use CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB). Tamanho global de rotação em bytes, ainda aceito para compatibilidade com versões anteriores; ignorado quando CB_MCP_LOG_ROTATION_MAX_SIZE_MB também está definido | Não definido |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Tamanho de rotação em MB para o arquivo de registro ERROR; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para ERROR | Herda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Tamanho de rotação em MB para o arquivo de registro WARNING; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para WARNING | Herda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Tamanho de rotação em MB para o arquivo de registro INFO; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para INFO | Herda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Tamanho de rotação em MB para o arquivo de registro DEBUG; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para DEBUG | Herda CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | Arquivos de backup rotacionados mantidos por arquivo de registro de cada nível (excluindo o arquivo ativo), aplicado a todos os níveis, a menos que seja substituído. 0 mantém somente o arquivo ativo (consulte Registro) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | Backups rotacionados mantidos para o arquivo de registro ERROR; substitui a contagem global para ERROR | Herda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Backups rotacionados mantidos para o arquivo de registro WARNING; substitui a contagem global para WARNING | Herda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Backups rotacionados mantidos para o arquivo de registro INFO; substitui a contagem global para INFO | Herda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Backups rotacionados mantidos para o arquivo de registro DEBUG; substitui a contagem global para DEBUG | Herda CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | Endpoint JWKS do provedor de identidade usado para verificar JWTs bearer. Ativa o OAuth quando definido junto com o emissor e o público (consulte Autorização OAuth 2.1) | Nenhum |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | Claim iss esperado do JWT. Obrigatório para ativar o OAuth | Nenhum |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Claim aud esperado do JWT. Obrigatório para ativar o OAuth | Nenhum |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | Algoritmo de assinatura JWT: um de RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL base pública deste servidor. Quando definida, publica metadados de recurso protegido RFC 9728 para que clientes compatíveis com PRM possam descobrir o IdP | Nenhum |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | Substitui o rótulo de escopo OAuth tratado como acesso de 'leitura' (anunciado no PRM e comparado com o claim scope/scp do token). Use quando seu IdP não puder emitir a forma canônica | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Substitui o rótulo de escopo OAuth tratado como acesso de 'gravação'; mesma semântica do rótulo de leitura | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | Ativa o registro de auditoria — um destino separado dos registros operacionais CB_MCP_LOG_*, com um esquema estável e retenção própria (consulte Auditoria) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | Destinos de auditoria separados por vírgulas: console, file ou ambos. console grava em stderr — nunca em stdout, que transporta o protocolo JSON-RPC em stdio | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | Caminho para o arquivo de registro de auditoria. Obrigatório quando file estiver entre os destinos; o nome do host e o ID do processo são inseridos antes da extensão (audit.log → audit.<host>.<pid>.log) | Nenhum |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | Tamanho máximo em MB que o arquivo de auditoria ativo pode atingir antes da rotação. 0 desativa a rotação baseada em tamanho | 10 (10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | Idade máxima do arquivo de auditoria ativo antes da rotação, como <value><unit>, em que a unidade é d (24 horas) ou w (7 dias) — por exemplo, 1d, 30d, 8w. 0 desativa a rotação baseada em intervalo | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | Backups rotacionados retidos por arquivo de auditoria, excluindo o arquivo ativo. Os backups são compactados com gzip. 0 não mantém nenhum. Isso limita um arquivo, não o diretório — consulte Auditoria | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | Registra os valores dos argumentos das ferramentas no registro de auditoria. Desativado por padrão — esta versão não tem redação, portanto, ativar essa opção grava os argumentos literalmente, incluindo corpos completos de documentos | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | Eventos de auditoria a suprimir: IDs de evento numéricos separados por vírgulas (por exemplo, 61490,61492) ou um arquivo com um ID por linha. Somente eventos filtráveis podem ser suprimidos | Nenhum |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | Provedor de embeddings para run_vector_query / run_vector_search: um de capella, openai, cohere, voyage, bedrock. Se não definido, a etapa de embeddings de ambas as ferramentas fica desativada até a configuração — consulte Configuração do provedor de embeddings | Nenhum |
CB_MCP_EMBEDDING_MODEL | --embedding-model | Nome/ID do modelo para o provedor de embeddings configurado | Nenhum |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | Chave de API para o provedor configurado. Não é usada por bedrock (usa a cadeia de credenciais da AWS / CB_MCP_EMBEDDING_MODEL_AWS_*) | Nenhum |
CB_MCP_EMBEDDING_MODEL_ENDPOINT | --embedding-model-endpoint | Substituição da URL base (um servidor local compatível com OpenAI ou a URL própria de uma implantação do Capella Model Service — obrigatória quando CB_MCP_EMBEDDING_MODEL_PROVIDER=capella) | Nenhum |
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID | --embedding-model-aws-access-key-id | ID da chave de acesso da AWS, somente para o provedor bedrock. Omita para usar a cadeia de credenciais padrão da AWS | Nenhum |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | Chave de acesso secreta da AWS, somente para o provedor bedrock | Nenhum |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | Região da AWS, somente para o provedor bedrock. Se não definida, usa a resolução de região própria do AWS SDK | Nenhum |
Servidor Operational Insights
O servidor operational-insights conecta-se a clusters autogerenciados do Operational Insights. Operational Insights é um banco de dados analítico em tempo real (RT-OLAP) para aplicativos em tempo real e inteligência operacional. O servidor não está disponível para o Capella. Ele usa o SDK couchbase-operational-insights. É executado como um processo próprio, separado do servidor operacional.
[!IMPORTANT]
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRINGé uma URL HTTP(S), não uma string de conexãocouchbase://— por exemplo,http://localhost:8095ouhttps://<host>:18095com TLS. Essa é a configuração incorreta mais comum.
Início rápido do Operational Insights
Do PyPI com uvx:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational-insights"],
"env": {
"CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
"CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
"CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
}
}
}
}
Com Docker:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
"-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
"-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
"couchbase/mcp-server:latest", "operational-insights"
]
}
}
}
Para usar o código-fonte, use a configuração do código-fonte operacional com operational-insights como último argumento e as variáveis acima.
Conexão e autenticação do Operational Insights
| Variável de ambiente | Argumento da CLI | Descrição |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | URL do endpoint (HTTP/HTTPS). Obrigatório |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | Nome de usuário |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | Senha |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | Certificado raiz (PEM) para um certificado de servidor autoassinado/não confiável |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | Certificado do cliente para mTLS — PEM (com uma chave) ou um pacote PKCS#12 (.p12/.pfx, sem chave). Requer uma URL https://; substitui nome de usuário/senha |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | Chave privada (PEM) do certificado do cliente. Deixe sem definir para PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | Senha de uma chave criptografada ou pacote PKCS#12 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | Tamanho máximo do resultado da consulta em bytes. Se não definido, não há limite. Quando definido, a leitura para ao atingir o limite e a resposta informa truncated: true; uma linha que ultrapassaria o limite não é retornada. Valores acima de 4 MiB (4194304) são limitados a 4 MiB, com um aviso em stderr na inicialização |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | Tempo limite em segundos para cada solicitação de consulta assíncrona: iniciar a consulta, verificar seu status, buscar resultados, descartar e cancelar. Para uma busca, ele cobre todo o download, portanto, uma leitura de resultado que demore mais do que isso falha. Aumente-o para resultados grandes ou conexões lentas. Inteiro positivo, padrão 30, máximo 600. Valores maiores são limitados a 600 com um aviso; qualquer outro valor inválido é registrado como aviso e 30 é usado |
Todas as configurações comuns se aplicam, com estas diferenças em relação ao servidor operacional:
- A porta padrão é
8001e o arquivo de log padrão émcp_server_operational_insights.log, permitindo que ambos os servidores sejam executados lado a lado. - Apenas um worker é compatível (
CB_MCP_WORKERS=1), pois os identificadores de consulta assíncrona ficam na memória do processo. - Ele não tem opções
CB_MCP_EMBEDDING_MODEL_*.
Ferramentas do Operational Insights
Todos os nomes, exceto get_server_configuration_status, têm o prefixo operational_insights_, para que ambos os servidores possam ser registrados em um cliente sem conflitos. A ferramenta de gravação (marcada com ✏️) não é carregada enquanto o modo somente leitura estiver ativado, que é o padrão.
Status do servidor
| Ferramenta | Descrição |
|---|---|
get_server_configuration_status | Mesma ferramenta do servidor operacional |
Descoberta de modelo de dados e esquema
| Ferramenta | Descrição |
|---|---|
operational_insights_get_databases_in_cluster | Listar bancos de dados |
operational_insights_get_scopes_in_database | Listar escopos em um banco de dados |
operational_insights_get_collections_in_scope | Listar coleções (conjuntos de dados) em um escopo |
operational_insights_get_schema_for_collection | Inferir o esquema JSON de uma coleção por amostragem |
Consulta e índice
| Ferramenta | Descrição |
|---|---|
operational_insights_list_indexes | Listar índices secundários de System.Metadata.Index |
operational_insights_explain_query | Explicar uma instrução SQL++ sem executá-la |
operational_insights_run_query_sync | Executar SQL++ e retornar linhas, até o limite de tamanho do resultado; também pode exportar. O modo somente leitura é aplicado no servidor |
operational_insights_run_query_async | Iniciar uma consulta de longa duração e retornar um query_handle sem aguardar as linhas; também é preferível para exportações grandes. O modo somente leitura é aplicado no servidor |
operational_insights_get_async_query_results | Consultar uma consulta assíncrona; retorna linhas (ou o destino da exportação) quando estiver pronta |
operational_insights_discard_async_query_results | Liberar os resultados de uma consulta assíncrona concluída |
operational_insights_cancel_async_query | Parar uma consulta assíncrona ainda em execução (permitido no modo somente leitura) |
operational_insights_create_index ✏️ | Criar um índice secundário por meio de CREATE INDEX |
Consultas assíncronas seguem um fluxo de iniciar → consultar → descartar ou cancelar: operational_insights_run_query_async retorna um query_handle, operational_insights_get_async_query_results é consultado até que esteja pronto; em seguida, operational_insights_discard_async_query_results libera os resultados ou operational_insights_cancel_async_query para uma consulta ainda em execução.
Exportar resultados grandes
Em vez de retornar linhas, operational_insights_run_query_sync e operational_insights_run_query_async podem envolver a instrução em COPY ... TO e gravar as linhas em um armazenamento de objetos externo. Informe os três itens copy_to_link (um link existente criado com CREATE LINK ... TYPE S3), copy_to_bucket e copy_to_path, além de, opcionalmente, copy_to_format (json, o padrão, ou parquet). A ferramenta retorna então uma confirmação sem linhas:
{
"success": true,
"exported": true,
"destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
"message": "Results were written to my-exports/exports/run1 as json. ..."
}
- Um destino parcial é rejeitado, em vez de retornar linhas silenciosamente.
- A ferramenta síncrona aguarda o upload completo; prefira a ferramenta assíncrona para exportações grandes.
- As exportações são bloqueadas no modo somente leitura (pois gravam em armazenamento externo), portanto, precisam de
CB_MCP_READ_ONLY_MODE=falseou de um token comcouchbase-mcp:write. csvnão é oferecido, pois requer um esquema de saída explícito que não pode ser inferido de umSELECTarbitrário.
Configuração comum
Essas configurações funcionam da mesma forma para ambos os servidores. Cada opção pode ser definida como variável de ambiente ou como sinalizador da CLI após o subcomando.
Controles de segurança
Siga estes princípios de segurança:
- Conceda ao usuário do banco de dados o mínimo de privilégios — o RBAC é o limite de segurança autoritativo (veja abaixo).
- Forneça apenas as ferramentas de que o agente precisa e desative as demais — cada ferramenta carregada pode ser chamada pelo LLM. Use o modo somente leitura e
CB_MCP_DISABLED_TOOLSpara manter a lista de ferramentas no mínimo. - Exija confirmação para ferramentas sensíveis que você mantiver — consulte Exigir confirmação.
Os controles abaixo formam três camadas, da mais abrangente à mais restrita. Use-os em conjunto — mas lembre-se de que nenhum deles substitui o RBAC.
[!IMPORTANT] As permissões RBAC do usuário do banco de dados são o controle de segurança autoritativo. Por exemplo, desativar
upsert_document_by_idedelete_document_by_idnão impede querun_sql_plus_plus_queryexecuteINSERT/UPDATE/DELETE/MERGE— somente o modo somente leitura ou a ausência de permissões RBAC impedem isso. Conceda ao usuário do banco de dados do servidor apenas as permissões necessárias.
Modo somente leitura
CB_MCP_READ_ONLY_MODE (padrão true) é a única opção para controlar gravações:
true— as ferramentas de gravação marcadas com ✏️ na lista de ferramentas de cada servidor não são carregadas, e consultas que modificam dados ou estruturas são bloqueadas.false— as ferramentas de gravação são carregadas e consultas que modificam dados são permitidas.
Desativar ferramentas
CB_MCP_DISABLED_TOOLS remove ferramentas completamente da descoberta. Aceita uma lista separada por vírgulas ou o caminho para um arquivo com um nome de ferramenta por linha (# inicia um comentário):
CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt
# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendations
No Capella, o servidor operacional também desativa automaticamente algumas ferramentas administrativas.
Exigir confirmação (elicitação)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS solicita que o usuário confirme antes da execução de uma ferramenta listada, usando a elicitação do MCP. Aceita os mesmos formatos de lista separada por vírgulas ou arquivo usados para ferramentas desativadas:
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
- Se o cliente for compatível com elicitação, o usuário será solicitado a confirmar antes da execução da ferramenta.
- Se não for, a ferramenta será executada sem confirmação, para manter a compatibilidade com versões anteriores.
- A confirmação requer uma sessão MCP, portanto, não pode ser combinada com HTTP sem estado (
CB_MCP_STATELESS_HTTP=trueouCB_MCP_WORKERSacima de 1). O servidor se recusa a iniciar com essa combinação. Atrás de um balanceador de carga, a confirmação requer sessões persistentes — consulte Balanceadores de carga.
Transportes
| Transporte | Usar para | Endpoint |
|---|---|---|
stdio (padrão) | Um cliente local que inicia o servidor como subprocesso | — |
http | Vários clientes compartilhando um servidor; compatível com OAuth, verificações de integridade e workers no servidor operacional | http://<host>:<port>/mcp |
Defina o transporte com CB_MCP_TRANSPORT, o endereço de vinculação com CB_MCP_HOST (padrão 127.0.0.1) e a porta com CB_MCP_PORT (a porta padrão de cada servidor quando não definida). Sem OAuth, o endpoint HTTP não tem autenticação.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http
Em seguida, aponte seu cliente para a URL:
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
Vários workers
Um processo usa no máximo cerca de um núcleo de CPU. --workers N (CB_MCP_WORKERS) executa N processos no mesmo host e porta; o número de núcleos disponíveis é um bom ponto de partida. Apenas o servidor operacional é compatível com workers. Com mais de um worker:
- O transporte
httpé obrigatório, e o servidor é executado no modo HTTP sem estado, pois as solicitações de um cliente podem chegar a workers diferentes. Você também pode definir--stateless-http=trueem um único worker, por exemplo, atrás de um balanceador de carga sem sessões persistentes. - Não é possível usar ferramentas que exigem confirmação.
- Cada processo grava seus próprios arquivos de log, identificados pelo host e pelo ID do processo (
mcp_server.<host>.<pid>.info.log) — um conjunto para o supervisor e outro para cada worker.
Balanceadores de carga
Você pode executar várias instâncias do servidor atrás de um balanceador de carga. Cada instância mantém suas sessões MCP na própria memória, portanto, a configuração do balanceador de carga determina o que funciona:
| Balanceador de carga | Configuração do servidor | Ferramentas que exigem confirmação |
|---|---|---|
Sessões persistentes, roteadas pelo cabeçalho de solicitação Mcp-Session-Id | Um worker, com estado (padrão) | Compatíveis |
| Sem sessões persistentes | --stateless-http=true | Não compatíveis — o servidor se recusa a iniciar se estiverem configuradas |
- Sem sessões persistentes, uma instância com estado rejeita todas as solicitações cuja sessão tenha sido criada em outra instância. Nesse caso, use o modo sem estado.
- Faça o roteamento pelo cabeçalho
Mcp-Session-Id, não por cookies. Muitos clientes MCP não mantêm cookies. - Se uma instância reiniciar ou ocorrer failover, suas sessões e quaisquer solicitações de confirmação pendentes serão perdidas. O cliente deverá iniciar uma nova sessão.
- As consultas assíncronas do Operational Insights mantêm seus
query_handlena memória da instância que iniciou a consulta, inclusive no modo sem estado. Consultar, descartar ou cancelar a consulta em outra instância retornaUnknown query_handle. Use essas ferramentas com uma única instância ou com sessões persistentes, para que todas as chamadas cheguem à instância que iniciou a consulta. O modo sem estado não enviaMcp-Session-Id, portanto, requer outra chave de afinidade, como o endereço IP do cliente.
Verificação de integridade
No modo HTTP, GET /health retorna {"status": "ok", "server": "<server>"} na porta MCP. É uma verificação de atividade: não se conecta ao cluster (portanto, uma interrupção do cluster não reinicia contêineres saudáveis), não requer autenticação mesmo com OAuth ativado e é atendida por todos os workers. Consulte Docker para ver exemplos de sondas.
Autorização OAuth 2.1
Com --transport=http, qualquer um dos servidores pode atuar como servidor de recursos OAuth 2.1, validando JWTs bearer em relação ao JWKS do seu provedor de identidade. Funciona com qualquer provedor OAuth 2.1/OIDC que publique um JWKS e não emite tokens nem gerencia usuários. As configurações de OAuth são ignoradas em stdio.
- O OAuth só é ativado quando
CB_MCP_OAUTH_JWT_JWKS_URI,CB_MCP_OAUTH_JWT_ISSUEReCB_MCP_OAUTH_JWT_AUDIENCEestão todos definidos; definir apenas alguns causa uma falha na inicialização. CB_MCP_OAUTH_MCP_BASE_URLtambém publica metadados de recursos protegidos RFC 9728 para que os clientes possam descobrir o servidor de autorização.- O acesso é controlado por dois escopos na declaração
scope/scpdo token:couchbase-mcp:read(ferramentas de leitura) ecouchbase-mcp:write(ferramentas de gravação). O acesso completo requer ambos. Renomeie-os comCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELse o seu IdP não puder emitir esses rótulos. Ambos os servidores usam os mesmos rótulos, portanto, uma única configuração de IdP atende aos dois.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http \
--oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
--oauth-issuer='https://auth.example.com/' \
--oauth-audience='couchbase-mcp-server' \
--oauth-mcp-base-url='<public_base_url_of_this_server>'
Consulte a documentação de OAuth do servidor operacional e do servidor Operational Insights para configurar o IdP.
Registro em log
Por padrão, cada servidor registra em stderr no nível info.
CB_MCP_LOG_LEVEL—off,error,warning,info(eventos de ciclo de vida e chamadas de ferramentas) oudebug.CB_MCP_LOG_SINKS—stderr,fileou ambos. Comfile, um arquivo rotativo por nível é gravado ao lado deCB_MCP_LOG_FILE(mcp_server.info.log,mcp_server.error.log, …).- Rotação e retenção —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(padrão de 1 MB) eCB_MCP_LOG_RETENTION_BACKUP_COUNT(padrão de 1) se aplicam a todos os níveis; substitua por nível comCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Tamanhos inválidos usam o padrão e geram um aviso na inicialização.CB_MCP_LOG_MAX_BYTESestá obsoleto. - Instantâneo da configuração — com o destino
file, um registro JSON do ambiente e da configuração do servidor com dados ocultados é gravado emmcp_server_config.log.jsona cada inicialização, para fins de suporte.
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file
Seu cliente MCP geralmente também captura o stderr do servidor — veja Configuração do cliente para saber onde. Detalhes: documentação de registro em log do servidor operacional e do servidor Operational Insights.
Auditoria
O registro de auditoria registra quem fez o quê e se a ação foi permitida — separado dos logs operacionais, que registram o que deu errado. O servidor MCP é a única camada capaz de responder a isso para um agente: cada solicitação chega ao cluster como um único usuário do banco de dados, e decisões como uma negação de escopo, um bloqueio de somente leitura ou uma confirmação recusada nunca chegam ao cluster.
A auditoria fica desativada por padrão. Ative-a com CB_MCP_AUDIT_LOG_ENABLED=true; ela grava no stderr, a menos que você defina CB_MCP_AUDIT_LOG_SINKS=file e CB_MCP_AUDIT_LOG_FILE_PATH.
# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
--audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
--audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
--audit-log-retention-max-backups=90
Os registros são linhas JSON que usam o mesmo vocabulário de campos do Couchbase Server e do Sync Gateway:
{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}
Como a auditoria funciona
- Identidade —
real_useridé o chamador:oauth(o assunto do token),local(o usuário do sistema operacional, em stdio) ouanonymous(HTTP sem OAuth, que gera um aviso na inicialização). - Correlação —
cidagrupa todos os registros de uma solicitação e é enviado comoclient_context_iddo SQL++, permitindo a correspondência exata comclientContextIddo Couchbase Server. Não há identificador de sessão, intencionalmente. - Eventos — um catálogo fixo e numerado (ciclo de vida, inicialização, token rejeitado, escopo negado, bloqueio de somente leitura, confirmação recusada/ignorada e um par de leitura/gravação por categoria de ferramenta).
queryesearchsão as exceções: cada um é registrado como um único evento, em vez de um par de leitura/gravação, porque não foi possível fazer essa distinção de forma confiável em superfícies orientadas por instruções e de pesquisa. As operações vetoriais estão incluídas nessas duas categorias. O catálogo completo é distribuído comodescriptor.jsonno pacote. O servidor operacional usa o bloco0xF000(61440), o Operational Insights usa0x10000(65536), e ambos compartilham0xE000(57344) para eventos principais. - Filtragem —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSsuprime eventos de leitura por ID numérico (por exemplo,61490,61492). Eventos de gravação e de segurança não podem ser desativados, assim como as categorias de evento únicoquery(61507, ou 65603 no Operational Insights) esearch(61510): um evento abrange tanto as gravações quanto as leituras de cada categoria, portanto desativá-lo faria com que um registro de mutação fosse perdido. - Rotação — por tamanho (
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, padrão 10) e idade (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, padrão1d), o que ocorrer primeiro;0desativa qualquer um dos dois. Os arquivos rotacionados recebem marcação de data e hora e são compactados com gzip; o arquivo ativo permanece em texto simples paratail -f. - Arquivos por processo — host e PID são inseridos no nome (
audit.log→audit.<host>.<pid>.log), para que processos simultâneos nunca compartilhem um arquivo. - A retenção é por arquivo —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(padrão 10) limita os backups de um arquivo. Cada novo processo grava um novo arquivo e nada remove os antigos; portanto, dimensione o volume ou limpe os arquivosaudit.*.log*antigos. - Falha aberta — se não for possível gravar o arquivo, o servidor continua atendendo e contabiliza os registros descartados;
get_server_configuration_statusinformawritten/dropped/write_errors. - Argumentos das ferramentas — registrados somente com
CB_MCP_AUDIT_LOG_TOOL_ARGS=true, que gera um aviso na inicialização. Esta versão não faz ocultação de dados, portanto os argumentos, incluindo corpos completos de documentos, são gravados literalmente.
Configuração do cliente
Cada cliente precisa de uma configuração de servidor do início rápido operacional ou do Operational Insights em seu próprio local de configuração. Os exemplos abaixo usam o servidor operacional.
Claude Desktop
- Abra o arquivo de configuração (consulte o guia de início rápido do MCP):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Adicione o servidor em
mcpServerse reinicie o Claude Desktop.
Logs: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consulte o guia de solução de problemas do MCP.
Cursor
- Acesse Cursor Settings > Tools & Integrations > MCP Tools (consulte a documentação de MCP do Cursor), ou use o link de um clique Install in Cursor — depois substitua a string de conexão e as credenciais de exemplo.
- Adicione a configuração em
mcpServerse salve. - Atualize a lista de servidores MCP para verificar se
couchbaseestá ativado.
Logs: no painel inferior, abra Output e selecione Cursor MCP.
Windsurf Editor
- Abra Command Palette > Windsurf MCP Configuration Panel ou Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (consulte a documentação de MCP do Windsurf).
- Clique em Add Server > Add custom server, cole a configuração e salve.
- Atualize a lista de servidores para verificar se
couchbaseestá ativado.
VS Code
O VS Code usa servers como chave de nível superior, em vez de mcpServers. Coloque a configuração em .vscode/mcp.json para um espaço de trabalho ou execute MCP: Open User Configuration para todos os espaços de trabalho (consulte a documentação de MCP do VS Code):
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Salvar o arquivo inicia o servidor; use as ações Running | Stop | n Tools acima dele para gerenciá-lo.
Logs: execute MCP: List Servers, selecione couchbase e depois Show Output.
JetBrains IDEs
- Instale o plugin AI Assistant ou Junie.
- Acesse Settings > Tools > AI Assistant (or Junie) > MCP Server, clique em +, adicione a configuração e clique em Apply.
- Passe o cursor sobre o status do servidor para ver suas ferramentas.
Logs: Help > Show Log in Finder (Explorer) > mcp > couchbase.
Docker
As imagens pré-compiladas são publicadas no Docker Hub como couchbase/mcp-server, e o servidor está listado no Docker MCP Catalog. Configure o contêiner com as mesmas variáveis de ambiente acima. Consulte a página do Docker Hub (DOCKER.md) para ver exemplos de tags, volumes e verificações de integridade.
Execução por HTTP — observe que o servidor deve se vincular a 0.0.0.0 para ser acessível de fora do contêiner:
docker run --rm \
-e CB_CONNECTION_STRING='<couchbase_connection_string>' \
-e CB_USERNAME='<database_user>' \
-e CB_PASSWORD='<database_password>' \
-e CB_MCP_TRANSPORT=http \
-e CB_MCP_HOST=0.0.0.0 \
-p 8000:8000 \
couchbase/mcp-server:latest operational
- Se o Couchbase estiver em execução na máquina host, use
couchbase://host.docker.internalcomo string de conexão (consulte Rede do Docker). Use--network=<your_network>para ingressar na rede de outro contêiner. - Acrescente
operational-insightsem vez deoperationalpara executar o servidor Operational Insights (porta8001).
Compilar a imagem a partir do código-fonte
docker build -t mcp/couchbase-src .
./build.sh [image-name] compila com os mesmos argumentos usados pela CI — define os argumentos de compilação GIT_COMMIT_HASH e BUILD_DATE e marca a imagem com latest e <short-commit> (nome padrão mcp/couchbase-src). Para compilar manualmente com os rótulos:
docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
--build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
-t mcp/couchbase-src .
# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest
Solução de problemas
Para ver os guias completos, consulte a documentação de solução de problemas do servidor operacional e do servidor Operational Insights, além das diretrizes de segurança do servidor operacional e do servidor Operational Insights. Verificações rápidas:
- Verifique a string de conexão, o nome de usuário e a senha ou os caminhos dos certificados.
- No Capella, verifique se o cluster permite conexões da máquina que executa o servidor.
- Verifique se o usuário do banco de dados pode acessar pelo menos um bucket.
- Se o cliente não encontrar
uv/uvx, informe o caminho absoluto emcommand. - Ao executar a partir do código-fonte, verifique o caminho do repositório na configuração e execute
uv syncdepois de obter as atualizações. - Chame
get_server_configuration_statuspara ver a configuração efetivamente resolvida pelo servidor e verifique os logs do cliente (consulte Configuração do cliente).
Perguntas frequentes
Como conecto o Claude Desktop ao Couchbase? Adicione a configuração de início rápido a claude_desktop_config.json e reinicie o Claude Desktop — consulte Configuração do cliente.
Posso usar isso com o Couchbase Capella? Sim, com o servidor operacional: a mesma configuração funciona com o Capella e com clusters autogerenciados, embora algumas ferramentas administrativas estejam disponíveis apenas em clusters autogerenciados (consulte Ferramentas). O servidor Operational Insights é exclusivo para clusters autogerenciados do Operational Insights.
É seguro permitir que um agente de IA grave no meu banco de dados? Por padrão, não há ferramentas de gravação carregadas e a execução de SQL++ que modifica dados é bloqueada. Se você ativar as gravações, ainda poderá desativar ferramentas individuais ou exigir confirmação — mas as permissões RBAC do seu usuário do Couchbase continuam sendo a verdadeira barreira de segurança. Consulte Controles de segurança.
Preciso conhecer SQL++? Não. Faça uma pergunta em linguagem simples e o assistente escreverá o SQL++ para run_sql_plus_plus_query. Ele também pode explicar um plano de consulta ou pedir recomendações ao Index Advisor.
STDIO ou Streamable HTTP? STDIO para um único cliente local. Streamable HTTP para compartilhar um servidor entre clientes, com OAuth. Consulte Transportes.
Este produto tem suporte oficial da Couchbase? Sim, com uma licença Couchbase AI Data Plane. Sem ela, os engenheiros da Couchbase oferecem ajuda em regime de melhores esforços por meio de issues do GitHub. Consulte Política de suporte.
Contribuição
Contribuições são bem-vindas — correções de bugs, recursos e documentação. Para relatar um bug ou pedir ajuda, abra uma issue no GitHub.
Consulte CONTRIBUTING.md para ver as instruções de configuração do ambiente de desenvolvimento, linting, testes, estrutura do projeto e fluxo de trabalho. Para começar:
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh
Testes de integração são executados em um cluster ativo. Exporte CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD e, opcionalmente, CB_MCP_TEST_BUCKET; os testes do Operational Insights também usam CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD e são ignorados quando essas variáveis não estão definidas. Em seguida, execute:
uv run --extra dev pytest tests/integration -v
Dados de uso, riscos de LLM e política de suporte
Coleta de dados de uso
Este produto coleta automaticamente dados de uso e desempenho (como nome e versão do produto) e informações do navegador (como endereço IP) (coletivamente, "Dados de uso"). A Couchbase usa os Dados de uso, juntamente com outros dados que você pode fornecer à Couchbase (como seu nome de usuário ou endereço de e-mail), para desenvolver e aprimorar nossos produtos, bem como orientar nossos programas de vendas e marketing. Não acessamos nem coletamos dados que você armazena nos produtos Couchbase. Usamos os Dados de uso para entender padrões de uso agregados e tornar nossos produtos mais úteis para você. Para obter mais informações sobre como a Couchbase coleta, protege e processa informações, consulte a Política de Privacidade da Couchbase, disponível em https://www.couchbase.com/privacy-policy.
Riscos associados a LLMs
- O uso de modelos de linguagem grandes e tecnologias semelhantes envolve riscos, incluindo a possibilidade de resultados imprecisos ou prejudiciais.
- A Couchbase não revisa nem avalia a qualidade ou a precisão desses resultados, e eles podem não refletir as opiniões da Couchbase.
- Você é o único responsável por decidir se usará modelos de linguagem grandes e tecnologias relacionadas, bem como por cumprir quaisquer termos de licença, termos de uso e políticas da sua organização que regem o uso dessas tecnologias.
Política de suporte
O Couchbase MCP Server é de código aberto e mantido por engenheiros da Couchbase. A forma de obter ajuda depende de como você o utiliza:
- Uso pela comunidade — relate bugs, faça perguntas e solicite recursos abrindo uma issue no GitHub. Os engenheiros da Couchbase monitoram o repositório e respondem conforme possível, sem compromisso de prazo para resposta. O portal de suporte da Couchbase não pode ajudar com o uso pela comunidade.
- Suporte empresarial — disponível mediante licenciamento do Couchbase AI Data Plane, que também inclui o Couchbase Agent Memory e o Couchbase Agent Catalog. Clientes licenciados recebem ajuda pelos canais habituais de suporte da Couchbase.
Agradecemos por usar e contribuir com o projeto!