Notebook-first demo
`main.ipynb` walks through the agent setup, MCP server lifecycle, sample questions, and final responses.
5
MCP tools for scoped Couchbase access
SQL++
Queries run in the inventory scope context
stdio
Simple local MCP transport for notebooks
Nebius
OpenAI-compatible model endpoint
Natural language meets travel-sample data.
The project turns Couchbase into a tool surface an agent can reason over. It is small enough to understand in one sitting, but structured like something you can extend into a real data assistant.
Read-only by default
SQL++ mutation statements are blocked unless you explicitly opt in with an environment variable.
Nebius-ready model path
Uses an OpenAI-compatible chat completions model configuration for Nebius-hosted LLMs.
Agent runtime with a clean MCP boundary.
The agent does not import Couchbase code directly. It discovers and calls tools through MCP, while the server owns credentials, query context, and safety checks.
User asks a travel question
Hotels, airports, airlines, routes, or landmarks can be queried naturally.
Agent selects an MCP tool
The OpenAI Agents SDK manages the tool loop and final answer generation.
Couchbase returns scoped results
The server applies the `travel-sample.inventory` query context.
# Install and configure python -m venv .venv source .venv/bin/activate pip install -e ".[notebook]" cp .env.example .env # Run the notebook jupyter lab main.ipynb # Or ask from the CLI couchbase-agent-demo \ "List the top 5 hotels by aggregate rating."
Tooling surface
The MCP server exposes a compact set of database tools designed for the `travel-sample` bucket and the `inventory` scope.
connection summary
Shows non-secret runtime configuration.
scopes and collections
Discovers available Couchbase collections.
SQL++ query
Runs bounded queries in the configured scope.
document lookup
Fetches one document by collection and ID.
sample queries
Gives the agent known-good SQL++ examples.
Bring your own Couchbase and Nebius keys.
The repo includes `.env.example` with the exact variables expected by the server. Keep real secrets local, load the `travel-sample` bucket, and start with read-only credentials.
Read the READMECOUCHBASE_HOST=couchbases://cb.example.cloud.couchbase.com COUCHBASE_BUCKET_NAME=travel-sample COUCHBASE_SCOPE_NAME=inventory COUCHBASE_USERNAME=your_couchbase_username COUCHBASE_PASSWORD=your_couchbase_password NEBIUS_API_KEY=your_nebius_api_key NEBIUS_BASE_URL=https://api.studio.nebius.ai/v1/ NEBIUS_MODEL=meta-llama/Meta-Llama-3.1-8B-Instruct COUCHBASE_ALLOW_MUTATIONS=false