Couchbase

oficial

Interaja 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.

Docs License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

Documentação completa: docs.couchbase.com/mcp-server

Couchbase Server MCP server

Sumário

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 users nos quais status = '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 products com estes campos: …" (requer CB_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 operacionalServidor Operational Insights
Use comUm cluster Couchbase (Capella ou autogerenciado)Um cluster autogerenciado do Operational Insights (não disponível no Capella)
Subcomandooperational (o padrão)operational-insights
String de conexãocouchbase:// / couchbases://URL HTTP(S), por exemplo, http://localhost:8095
Variáveis de credenciaisCB_CONNECTION_STRING, CB_USERNAME, …CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, …
Ferramentas52 — integridade do cluster, esquema, KV, SQL++, índices, pesquisa de texto completo e vetorial, desempenho de consultas13 — esquema, SQL++ (síncrono e assíncrono), índices, exportações
Porta HTTP padrão80008001
Arquivo de log padrãomcp_server.logmcp_server_operational_insights.log

Atualmente, o subcomando é opcional para o servidor operacional — um couchbase-mcp-server sem 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 com uvx 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 ambienteArgumento CLIDescrição
CB_CONNECTION_STRING--connection-stringString de conexão com o cluster. Obrigatório
CB_USERNAME / CB_PASSWORD--username / --passwordAutenticação básica
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH--client-cert-path / --client-key-pathAutenticação mTLS
CB_CA_CERT_PATH--ca-cert-pathCertificado 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

FerramentaDescrição
get_server_configuration_statusStatus 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_connectionVerificar as credenciais do cluster conectando-se a ele
get_cluster_health_and_servicesIntegridade do cluster e serviços em execução, com filtragem opcional por meio de service_types
get_client_connectivity_reportDiagnó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

FerramentaDescrição
get_buckets_in_clusterListar todos os buckets do cluster
get_scopes_in_bucketListar todos os scopes de um bucket
get_collections_in_scopeListar todas as collections de um scope (requer o serviço Query)
get_scopes_and_collections_in_bucketListar todos os scopes e collections de um bucket
get_schema_for_collectionInferir 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)

FerramentaDescrição
get_document_by_idObter um documento pelo ID
lookup_subdocumentLer 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

FerramentaDescrição
run_sql_plus_plus_queryExecutar 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_queryGerar e avaliar um plano EXPLAIN: metadados, plano extraído e constatações
get_index_advisor_recommendationsRecomendações do Index Advisor para uma consulta SQL++
list_indexesListar í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.

FerramentaDescrição
list_search_indexesLista índices Search — no nível do cluster, por bucket ou por escopo
get_search_index_definitionDefinição completa de um índice Search (mapeamentos, analisadores, parâmetros do plano)
run_searchExecuta 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.

FerramentaDescrição
run_vector_queryPesquisa 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_searchPesquisa 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

FerramentaDescrição
get_longest_running_queriesConsultas de execução mais longa por tempo médio de serviço
get_most_frequent_queriesConsultas executadas com maior frequência
get_queries_with_largest_response_sizesConsultas com os maiores tamanhos de resposta
get_queries_with_large_result_countConsultas com as maiores quantidades de resultados
get_queries_using_primary_indexConsultas que usam um índice primário
get_queries_not_using_covering_indexConsultas que não usam um índice de cobertura
get_queries_not_selectiveConsultas 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.

FerramentaDescrição
get_cluster_query_vitalsIntegridade do mecanismo de consulta: taxa de solicitações, solicitações ativas/em fila, memória, GC, tempo de atividade. Requer ro_admin
get_active_queriesConsultas 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.

FerramentaEndpoint necessário
get_cluster_metricsREST de gerenciamento (/pools/default/stats/range)
get_cluster_tasksREST de gerenciamento (/pools/default/tasks)
get_bucket_configREST de gerenciamento (/pools/default/buckets[/<name>])
get_cluster_health_snapshotREST de gerenciamento, além de endpoints por nó
get_cluster_system_eventsREST de gerenciamento (/events)
get_index_statsREST do serviço Index (o /api/v1/stats de cada indexador)
get_cluster_query_vitalsREST do serviço Query (/admin/vitals)
get_active_queriesREST do serviço Query (/admin/active_requests)
delete_active_queryREST do serviço Query (DELETE /admin/active_requests/{id})
discover_tool_input_valuesNenhum (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_PROVIDERObrigatórioOpcionalObservações
capellaCB_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
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINTDefina o endpoint para usar um servidor local compatível com OpenAI (Ollama, vLLM, LM Studio)
cohereCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
voyageCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
bedrockCB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGIONModelos 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 ambienteArgumento da CLIDescriçãoPadrão
CB_CONNECTION_STRING--connection-stringString de conexão com o cluster CouchbaseObrigatório
CB_USERNAME--usernameNome de usuário com acesso aos buckets necessários para autenticação básicaObrigatório (ou Certificado e Chave do Cliente necessários para mTLS)
CB_PASSWORD--passwordSenha para autenticação básicaObrigatório (ou Certificado e Chave do Cliente necessários para mTLS)
CB_CLIENT_CERT_PATH--client-cert-pathCaminho para o arquivo de certificado do cliente para autenticação mTLSObrigatório se estiver usando mTLS (ou Nome de usuário e Senha obrigatórios)
CB_CLIENT_KEY_PATH--client-key-pathCaminho para o arquivo de chave do cliente para autenticação mTLSObrigatório se estiver usando mTLS (ou Nome de usuário e Senha obrigatórios)
CB_CA_CERT_PATH--ca-cert-pathCaminho 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-modeImpede 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--transportModo de transporte: stdio, httpstdio
CB_MCP_HOST--hostHost para o modo de transporte HTTP127.0.0.1
CB_MCP_PORT--portPorta para o modo de transporte HTTP8000
CB_MCP_WORKERS--workersNú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-httpProcessa 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-toolsFerramentas a desativar (consulte Desativar ferramentas)Nenhuma
CB_MCP_CONFIRMATION_REQUIRED_TOOLS--confirmation-required-toolsFerramentas 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-levelNível de registro do servidor MCP: off, debug, info, warning, error (consulte Registro)info
CB_MCP_LOG_SINKS--log-sinksDestinos de registro separados por vírgulas: stderr, file ou ambos (consulte Registro)stderr
CB_MCP_LOG_FILE--log-fileCaminho 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-mbTamanho 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ção1 (1 MB)
CB_MCP_LOG_MAX_BYTES--log-max-bytesObsoleto — 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á definidoNão definido
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-mbTamanho de rotação em MB para o arquivo de registro ERROR; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para ERRORHerda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB--log-warning-rotation-max-size-mbTamanho de rotação em MB para o arquivo de registro WARNING; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para WARNINGHerda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB--log-info-rotation-max-size-mbTamanho de rotação em MB para o arquivo de registro INFO; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para INFOHerda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB--log-debug-rotation-max-size-mbTamanho de rotação em MB para o arquivo de registro DEBUG; substitui CB_MCP_LOG_ROTATION_MAX_SIZE_MB para DEBUGHerda CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_RETENTION_BACKUP_COUNT--log-retention-backup-countArquivos 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-countBackups rotacionados mantidos para o arquivo de registro ERROR; substitui a contagem global para ERRORHerda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countBackups rotacionados mantidos para o arquivo de registro WARNING; substitui a contagem global para WARNINGHerda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countBackups rotacionados mantidos para o arquivo de registro INFO; substitui a contagem global para INFOHerda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countBackups rotacionados mantidos para o arquivo de registro DEBUG; substitui a contagem global para DEBUGHerda CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uriEndpoint 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-issuerClaim iss esperado do JWT. Obrigatório para ativar o OAuthNenhum
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceClaim aud esperado do JWT. Obrigatório para ativar o OAuthNenhum
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmAlgoritmo de assinatura JWT: um de RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL base pública deste servidor. Quando definida, publica metadados de recurso protegido RFC 9728 para que clientes compatíveis com PRM possam descobrir o IdPNenhum
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelSubstitui 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ônicacouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelSubstitui o rótulo de escopo OAuth tratado como acesso de 'gravação'; mesma semântica do rótulo de leituracouchbase-mcp:write
CB_MCP_AUDIT_LOG_ENABLED--audit-log-enabledAtiva 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-sinksDestinos de auditoria separados por vírgulas: console, file ou ambos. console grava em stderr — nunca em stdout, que transporta o protocolo JSON-RPC em stdioconsole
CB_MCP_AUDIT_LOG_FILE_PATH--audit-log-file-pathCaminho 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-mbTamanho máximo em MB que o arquivo de auditoria ativo pode atingir antes da rotação. 0 desativa a rotação baseada em tamanho10 (10 MB)
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL--audit-log-rotation-intervalIdade 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 intervalo1d
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS--audit-log-retention-max-backupsBackups 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 Auditoria10
CB_MCP_AUDIT_LOG_TOOL_ARGS--audit-log-tool-argsRegistra 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 documentosfalse
CB_MCP_AUDIT_LOG_DISABLED_EVENTS--audit-log-disabled-eventsEventos 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 suprimidosNenhum
CB_MCP_EMBEDDING_MODEL_PROVIDER--embedding-model-providerProvedor 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 embeddingsNenhum
CB_MCP_EMBEDDING_MODEL--embedding-modelNome/ID do modelo para o provedor de embeddings configuradoNenhum
CB_MCP_EMBEDDING_MODEL_API_KEY--embedding-model-api-keyChave 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-endpointSubstituiçã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-idID da chave de acesso da AWS, somente para o provedor bedrock. Omita para usar a cadeia de credenciais padrão da AWSNenhum
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyChave de acesso secreta da AWS, somente para o provedor bedrockNenhum
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionRegião da AWS, somente para o provedor bedrock. Se não definida, usa a resolução de região própria do AWS SDKNenhum

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ão couchbase:// — por exemplo, http://localhost:8095 ou https://<host>:18095 com 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 ambienteArgumento da CLIDescrição
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING--connection-stringURL do endpoint (HTTP/HTTPS). Obrigatório
CB_OPERATIONAL_INSIGHTS_USERNAME--usernameNome de usuário
CB_OPERATIONAL_INSIGHTS_PASSWORD--passwordSenha
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH--ca-cert-pathCertificado raiz (PEM) para um certificado de servidor autoassinado/não confiável
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH--client-cert-pathCertificado 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-pathChave privada (PEM) do certificado do cliente. Deixe sem definir para PKCS#12
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD--client-cert-passwordSenha de uma chave criptografada ou pacote PKCS#12
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE--operational-insights-query-result-max-sizeTamanho 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-timeoutTempo 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 é 8001 e 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

FerramentaDescrição
get_server_configuration_statusMesma ferramenta do servidor operacional

Descoberta de modelo de dados e esquema

FerramentaDescrição
operational_insights_get_databases_in_clusterListar bancos de dados
operational_insights_get_scopes_in_databaseListar escopos em um banco de dados
operational_insights_get_collections_in_scopeListar coleções (conjuntos de dados) em um escopo
operational_insights_get_schema_for_collectionInferir o esquema JSON de uma coleção por amostragem

Consulta e índice

FerramentaDescrição
operational_insights_list_indexesListar índices secundários de System.Metadata.Index
operational_insights_explain_queryExplicar uma instrução SQL++ sem executá-la
operational_insights_run_query_syncExecutar 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_asyncIniciar 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_resultsConsultar uma consulta assíncrona; retorna linhas (ou o destino da exportação) quando estiver pronta
operational_insights_discard_async_query_resultsLiberar os resultados de uma consulta assíncrona concluída
operational_insights_cancel_async_queryParar 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=false ou de um token com couchbase-mcp:write.
  • csv não é oferecido, pois requer um esquema de saída explícito que não pode ser inferido de um SELECT arbitrá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_TOOLS para 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_id e delete_document_by_id não impede que run_sql_plus_plus_query execute INSERT/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=true ou CB_MCP_WORKERS acima 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

TransporteUsar paraEndpoint
stdio (padrão)Um cliente local que inicia o servidor como subprocesso—
httpVários clientes compartilhando um servidor; compatível com OAuth, verificações de integridade e workers no servidor operacionalhttp://<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=true em 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 cargaConfiguração do servidorFerramentas que exigem confirmação
Sessões persistentes, roteadas pelo cabeçalho de solicitação Mcp-Session-IdUm worker, com estado (padrão)Compatíveis
Sem sessões persistentes--stateless-http=trueNã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_handle na memória da instância que iniciou a consulta, inclusive no modo sem estado. Consultar, descartar ou cancelar a consulta em outra instância retorna Unknown 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 envia Mcp-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_ISSUER e CB_MCP_OAUTH_JWT_AUDIENCE estão todos definidos; definir apenas alguns causa uma falha na inicialização.
  • CB_MCP_OAUTH_MCP_BASE_URL també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/scp do token: couchbase-mcp:read (ferramentas de leitura) e couchbase-mcp:write (ferramentas de gravação). O acesso completo requer ambos. Renomeie-os com CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL se 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) ou debug.
  • CB_MCP_LOG_SINKS — stderr, file ou ambos. Com file, um arquivo rotativo por nível é gravado ao lado de CB_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) e CB_MCP_LOG_RETENTION_BACKUP_COUNT (padrão de 1) se aplicam a todos os níveis; substitua por nível com CB_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_BYTES está 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 em mcp_server_config.log.json a 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) ou anonymous (HTTP sem OAuth, que gera um aviso na inicialização).
  • Correlação — cid agrupa todos os registros de uma solicitação e é enviado como client_context_id do SQL++, permitindo a correspondência exata com clientContextId do 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). query e search sã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 como descriptor.json no pacote. O servidor operacional usa o bloco 0xF000 (61440), o Operational Insights usa 0x10000 (65536), e ambos compartilham 0xE000 (57344) para eventos principais.
  • Filtragem — CB_MCP_AUDIT_LOG_DISABLED_EVENTS suprime 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 único query (61507, ou 65603 no Operational Insights) e search (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ão 1d), o que ocorrer primeiro; 0 desativa 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 para tail -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 arquivos audit.*.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_status informa written / 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
  1. 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
  2. Adicione o servidor em mcpServers e reinicie o Claude Desktop.

Logs: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Consulte o guia de solução de problemas do MCP.

Cursor
  1. 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.
  2. Adicione a configuração em mcpServers e salve.
  3. Atualize a lista de servidores MCP para verificar se couchbase está ativado.

Logs: no painel inferior, abra Output e selecione Cursor MCP.

Windsurf Editor
  1. 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).
  2. Clique em Add Server > Add custom server, cole a configuração e salve.
  3. Atualize a lista de servidores para verificar se couchbase está 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
  1. Instale o plugin AI Assistant ou Junie.
  2. Acesse Settings > Tools > AI Assistant (or Junie) > MCP Server, clique em +, adicione a configuração e clique em Apply.
  3. 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.internal como string de conexão (consulte Rede do Docker). Use --network=<your_network> para ingressar na rede de outro contêiner.
  • Acrescente operational-insights em vez de operational para executar o servidor Operational Insights (porta 8001).
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 em command.
  • Ao executar a partir do código-fonte, verifique o caminho do repositório na configuração e execute uv sync depois de obter as atualizações.
  • Chame get_server_configuration_status para 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!