# Couchbase (Vector & NoSQL) MCP for AI Agents MCP

> Couchbase (Vector & NoSQL) provides natural language access to complex, structured data in your Couchbase cluster. It lets you execute sophisticated N1QL queries against JSON documents and perform high-speed KNN vector similarity searches across massive datasets using only conversation.

## Overview
- **Category:** databases
- **Price:** Free
- **Tags:** nosql, vector-search, knn, n1ql, embeddings, high-performance-computing

## Description

Need to talk to a database that handles everything from standard records to advanced semantic vectors? This MCP connects your entire Couchbase (Capella or self-hosted) cluster to your AI agent, giving you full control over both NoSQL data and complex vector storage through simple dialogue. Instead of writing boilerplate code for every search type, you just ask what you need.

This single connection lets your agent read document metadata using unique keys, run explicit SQL queries across entire collections, or find things based on meaning alone by mapping embeddings to vectors. If managing diverse data types—like structured records mixed with unstructured text and semantic similarity indexes—is a headache, this is what you need. You connect it via Vinkius, and suddenly your AI client can query the whole catalog of data sources using natural language.

Your agent won't just search; it will structure the results, pulling out exactly the JSON payload or specific field values you asked for.

## Tools

### list_buckets
This tool identifies the major routing spaces within your database environment.

### list_scopes
It retrieves detailed logging showing all defined scopes and collections available in your data structure.

### list_indexes
This tool enumerates all active, structured search indexes attached to the cluster.

### execute_n1ql_query
You can run complex queries using N1QL constraints to generate and retrieve specific JSON payloads.

### vector_search
This executes a structured search, mapping structural KNN vectors to find semantic similarities via an index.

### get_document
Fetch and retrieve the full internal mapped properties from specific Couchbase key-value documents.

### fts_search
Perform structural text extractions by matching query strings against advanced content indexes.

## Prompt Examples

**Prompt:** 
```
What are the main product types and their pricing?
```

**Response:** 
```
**Product Overview: Travel Samples**

*   **Economy Flight:** $85.00 (Min 1 person)
*   **Local Tour:** $45.00 (Per adult)
*   **Premium Package:** $320.00 (Includes transport & dinner)
```

**Prompt:** 
```
I need to find any documents related to 'cybersecurity compliance'.
```

**Response:** 
```
**Vector Search Results (Top 3 Matches)**

| Rank | Document Title | Similarity Score |
| :--- | :--- | :---: |
| 1 | Q3 Security Audit Report | 0.98 |
| 2 | Data Retention Policy v4.1 | 0.91 |
| 3 | Compliance Checklist for APIs | 0.75 |

The top result suggests a deep dive into security audits is warranted.
```

**Prompt:** 
```
List all available indexes so I know what's indexed.
```

**Response:** 
```
I found three active search indexes for you:

*   `customer-lookup`: Optimized for general user searches.
*   `vector-index-v1`: Used for semantic similarity matching (KNN).
*   `fts-content-search`: Handles full text extraction across all document bodies. 

Which kind of search are you running next?
```

## Capabilities

### Querying structured NoSQL documents
You can run complex N1QL queries to pull specific JSON fields and records across your entire database structure.

### Finding similar items via vectors
Execute high-speed KNN vector searches, locating textual or semantic matches by mapping embeddings against existing indices.

### Retrieving specific document details
Fetch the full internal properties and data maps for any given document key within a collection.

### Searching full-text content
Perform text searches across large content trees using advanced Full-Text Search indexes.

### Auditing and navigating the database structure
Identify all existing buckets, scopes, and collections to understand how your data is organized in the cluster.

## Use Cases

### Debugging an application's search flow
A developer needs to check if a new feature correctly pulls related data. They ask their agent to `get_document` using the main user ID, and then use `list_indexes` to verify that all necessary lookup indexes are active before proceeding.

### Finding policy documents by topic
Instead of keyword matching, a compliance officer needs to find policies related to 'GDPR data retention.' They ask the agent to perform a `vector_search` using an embedding for that topic, quickly returning semantically relevant files.

### Extracting metrics from sales records
A product manager needs a report showing total revenue and item count. They prompt the agent with an N1QL query via `execute_n1ql_query` targeting specific fields, generating a precise JSON structure for analysis.

### Mapping out data segmentation
A Data Architect needs to understand the boundaries of their system. They prompt the agent to run `list_buckets`, followed by `list_scopes` and `list_indexes`, generating a complete map of all available storage containers.

## Benefits

- Find exact documents quickly. By using the `get_document` tool, your agent retrieves complete internal properties for any unique key, eliminating manual lookups.
- Move beyond simple keyword searches. The `vector_search` capability finds results based on meaning (similarity) rather than just matching words.
- Handle complex data types easily. Use `execute_n1ql_query` to write sophisticated SQL-like commands that pull structured JSON payloads from deeply nested records.
- Audit your setup thoroughly. Running `list_scopes` and `list_buckets` lets you map the entire database structure, knowing exactly where every piece of data lives.
- Search everything text-based. The `fts_search` tool performs structural content matching across large documents, ideal for knowledge bases.

## How It Works

The bottom line is, you get instant access to query and search your entire NoSQL and vector dataset without writing database-specific code.

1. Subscribe to this MCP and provide your Couchbase URL, database username, and password.
2. Your AI client uses these credentials to connect directly to the specified Couchbase cluster endpoints.
3. You interact by asking natural language questions; the agent translates that into specific data operations like running N1QL queries or executing vector searches.

## Frequently Asked Questions

**How do I query complex data structures using the Couchbase (Vector & NoSQL) MCP?**
You simply ask your agent to run a structured query. Instead of writing boilerplate SQL, you tell it what fields and criteria you need, and it executes N1QL constraints to deliver the exact JSON payload.

**Can this MCP find things that are related by meaning, not just words?**
Yes. You can use vector search capabilities within the Couchbase (Vector & NoSQL) MCP. This finds semantic matches using your embeddings, which is critical for advanced knowledge retrieval.

**Is this better than querying a traditional relational database?**
It handles variety better. If your data includes documents, JSON records, and vector metadata all in one place, the Couchbase (Vector & NoSQL) MCP manages that complexity for you, letting you treat it like one single source.

**What if I only have a document key? How do I get its data?**
You can use the dedicated retrieval tool to fetch the full internal properties of any specific document. This gives you all the associated metadata and content mapped to that unique key.

**How does Couchbase (Vector & NoSQL) help with data organization?**
The MCP lets your agent map out your entire cluster, listing buckets, scopes, and indexes. This gives you a clear audit of where all the different types of data are stored.