🪷 LangGraph MCP Agent

A LangChain + LangGraph ReAct agent that talks to Couchbase through the Model Context Protocol (MCP)

Give a large language model a live database — without writing a single custom tool.

🌐 Live Project Website  ·  📓 Tutorial Notebook  ·  🚀 Deploy your own

---

✨ What is this?

This project demonstrates how to build a ReAct (Reasoning + Acting) agent that can query, reason about, and answer questions over a Couchbase database in plain English.

The magic ingredient is the Model Context Protocol (MCP) — an open standard that acts like a universal adapter between AI models and the outside world. Instead of hand-writing a dozen database functions and gluing them to the LLM, the agent discovers its tools at runtime from an MCP server. Change the server config and the same agent instantly works against a completely different system.

In one sentence: LangGraph provides the brain (the ReAct loop), MCP provides the hands (the tools), and Couchbase provides the knowledge (the data).

---

🧠 What is the Model Context Protocol (MCP)?

MCP is an open standard that standardizes how AI assistants connect to external data sources, tools, and systems — replacing bespoke, one-off integrations with a single common interface.

Goal	What it means here
Standardized communication	One protocol instead of N custom database connectors.
Secure data access	The MCP server controls exactly what the model can see and do (e.g. read-only mode).
Tool use & actionability	The LLM doesn't just read data — it can act through exposed tools.
Interoperability	Swap Couchbase for any other MCP server without touching agent code.

MCP uses a client–server architecture:

• MCP Client / Host — the application that wants data or capabilities. Here, this app (via LangChain) is the client.
• MCP Server — a lightweight program that exposes a data source or tool. Here, mcp-server-couchbase exposes Couchbase.

---

🏗️ Architecture

┌──────────────┐     natural language      ┌───────────────────────────┐
│    You 🧑     │ ───────────────────────▶  │   Streamlit Chat UI       │
└──────────────┘                            │        (app.py)           │
                                            └────────────┬──────────────┘
                                                         │
                                          ┌──────────────▼───────────────┐
                                          │  LangGraph ReAct Agent        │
                                          │  create_react_agent(llm,tools)│
                                          │  reason → act → observe → …   │
                                          └──────┬─────────────────┬──────┘
                                                 │ LLM             │ tools discovered
                                                 ▼                 ▼ via MCP
                                        ┌─────────────┐   ┌─────────────────────────┐
                                        │  OpenAI     │   │ langchain-mcp-adapters   │
                                        │  (reasoning)│   │  MultiServerMCPClient    │
                                        └─────────────┘   └───────────┬─────────────┘
                                                                      │ stdio (MCP)
                                                          ┌───────────▼─────────────┐
                                                          │  mcp-server-couchbase    │
                                                          └───────────┬─────────────┘
                                                                      │ N1QL / SDK
                                                          ┌───────────▼─────────────┐
                                                          │      Couchbase 🗄️        │
                                                          └──────────────────────────┘

---

🔁 How the ReAct loop works

The agent runs a Reason → Act → Observe cycle until it can answer:

1. Reason — the LLM reads your question and decides what it needs.
2. Act — it calls an MCP tool (e.g. run a N1QL query, list collections).
3. Observe — the tool result flows back into the model's context.
4. Repeat — until the model has enough information, then it writes the final answer.

You never write the tools — they arrive from the MCP server. Read more about LangGraph's prebuilt agent in the official docs.

---

🚀 Quickstart

1. Clone & install

git clone https://github.com/tirth1263/LangGraph-MCP-Agent.git
cd LangGraph-MCP-Agent
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure

cp .env.example .env

Fill in .env:

OPENAI_API_KEY=sk-...
CB_CONNECTION_STRING=couchbases://cb.<cluster-id>.cloud.couchbase.com
CB_USERNAME=your-db-username
CB_PASSWORD=your-db-password
CB_BUCKET_NAME=travel-sample
READ_ONLY_QUERY_MODE=true

💡 No database yet? Spin up a free cluster on Couchbase Capella and load the built-in travel-sample bucket in a couple of clicks.

3. Run the app

streamlit run app.py

Then open the URL Streamlit prints and start chatting with your data.

4. Or follow the notebook

Prefer a guided, step-by-step walkthrough? Open notebook/langgraph_mcp_couchbase_tutorial.ipynb.

---

💬 Example questions

Once connected to the travel-sample bucket, try:

• "How many airports are in the bucket? List five of them."
• "Find hotels in San Francisco and summarize their price ranges."
• "Which airlines fly out of SFO?"
• "What's the average review rating of hotels that allow pets?"

The agent translates each into N1QL queries via MCP, reasons over the results, and replies in natural language.

---

🧩 Project structure

LangGraph-MCP-Agent/
├── app.py                                   # Streamlit ReAct-agent chat app
├── notebook/
│   └── langgraph_mcp_couchbase_tutorial.ipynb   # Step-by-step tutorial
├── requirements.txt                         # Python dependencies
├── .env.example                             # Config template
├── docs/                                    # Live website (GitHub Pages)
├── LICENSE                                  # MIT
└── README.md

---

🌐 Deploy your own live app

The Streamlit agent needs your API keys and a running Couchbase cluster, so it can't be a static page — but you can publish an interactive instance for free:

1. Click the badge and sign in to Streamlit Community Cloud with GitHub.
2. Point it at this repo, main branch, app.py.
3. Add your secrets (OPENAI_API_KEY, CB_*) in the app settings.
4. Deploy — you'll get a public *.streamlit.app URL.

The project showcase website (this repo's docs/ folder) is already published live via GitHub Pages.

---

🛠️ Tech stack

Layer	Technology
Agent framework	LangGraph create_react_agent
LLM orchestration	LangChain
Tool protocol	Model Context Protocol + langchain-mcp-adapters
Data source	Couchbase via mcp-server-couchbase
Reasoning model	OpenAI (configurable)
UI	Streamlit

---

🙏 Credits & references

• Inspired by the awesome-ai-apps collection by Arindam200.
• LangGraph ReAct agent reference
• Model Context Protocol

📄 License

Released under the MIT License.

If this helped you understand MCP + agents, consider giving it a ⭐