Skip to content

fix LangChainMCP docs #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 26, 2025
+81 −105
Merged

fix LangChainMCP docs #347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified docs/content/advanced/images/export.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
186 changes: 81 additions & 105 deletions docs/content/advanced/langchain_mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,24 @@ This document describe how to re-use the configuration tested in the **AI Optimi

**NOTICE**: Only `Ollama` or `OpenAI` configurations are currently supported. Full support will come.

## Export config
In the **AI Optimizer & Toolkit** web interface, after have tested a configuration, in `Settings/Client Settings`:

![Client Settings](./images/export.png)

and **ONLY** if have been selected `Ollama` or `OpenAI` providers for **both** chat and embeddings models:

* select the checkbox `Include Sensitive Settings`
* press button `Download LangchainMCP` to download a zip file containing a full project template to run current selected AI Optimizer configuration.
* unzip the file in a <PROJECT_DIR> dir.

To run it, follow the next steps.

**NOTICE**:
* if you want to run the application in another server, remember to change in the optimizer_settings.json any reference no more local, like hostname for LLM servers, Database, wallet dir and so on.
* if you don't see the `Download LangchainMCP` check again if you have selected Ollama or OpenAI for both chat and the vectorstore embedding model.


## Pre-requisites.
You need:
- Node.js: v20.17.0+
Expand All @@ -23,7 +41,7 @@ You need:
- Claude Desktop free

## Setup
With **[`uv`](https://docs.astral.sh/uv/getting-started/installation/)** installed, run the following commands in your current project directory `<PROJECT_DIR>/src/client/mcp/rag/`:
With **[`uv`](https://docs.astral.sh/uv/getting-started/installation/)** installed, run the following commands in your current project directory `<PROJECT_DIR>`:

```bash
uv init --python=3.11 --no-workspace
Expand All @@ -32,147 +50,105 @@ source .venv/bin/activate
uv add mcp langchain-core==0.3.52 oracledb~=3.1 langchain-community==0.3.21 langchain-huggingface==0.1.2 langchain-openai==0.3.13 langchain-ollama==0.3.2
```

## Export config
In the **AI Optimizer & Toolkit** web interface, after tested a configuration, in `Settings/Client Settings`:

![Client Settings](./images/export.png)

* select the checkbox `Include Sensitive Settings`
* press button `Download Settings` to download configuration in the project directory: `src/client/mcp/rag` as `optimizer_settings.json`.
* in `<PROJECT_DIR>/src/client/mcp/rag/rag_base_optimizer_config_mcp.py` change filepath with the absolute path of your `optimizer_settings.json` file.


## Standalone client
There is a client that you can run without MCP via commandline to test it:

```bash
uv run rag_base_optimizer_config.py
```

## Quick test via MCP "inspector"

* Run the inspector:
There is a client that let you run the service via command-line, to test it without an MCP client, in your `<PROJECT_DIR>`:

```bash
npx @modelcontextprotocol/inspector uv run rag_base_optimizer_config_mcp.py
```

* connect to the port `http://localhost:6274/` with your browser
* setup the `Inspector Proxy Address` with `http://127.0.0.1:6277`
* test the tool developed.


## Claude Desktop setup

* In **Claude Desktop** application, in `Settings/Developer/Edit Config`, get the `claude_desktop_config.json` to add the references to the local MCP server for RAG in the `<PROJECT_DIR>/src/client/mcp/rag/`:
```json
{
"mcpServers": {
...
,
"rag":{
"command":"bash",
"args":[
"-c",
"source <PROJECT_DIR>/src/client/mcp/rag/.venv/bin/activate && uv run <PROJECT_DIR>/src/client/mcp/rag/rag_base_optimizer_config_mcp.py"
]
}
}
}
uv run rag_base_optimizer_config_direct.py "[YOUR_QUESTION]"
```
* In **Claude Desktop** application, in `Settings/General/Claude Settings/Configure`, under `Profile` tab, update fields like:
- `Full Name`
- `What should we call you`

and so on, putting in `What personal preferences should Claude consider in responses?`
the following text:

```
#INSTRUCTION:
Always call the rag_tool tool when the user asks a factual or information-seeking question, even if you think you know the answer.
Show the rag_tool message as-is, without modification.
```
This will impose the usage of `rag_tool` in any case.

**NOTICE**: If you prefer, in this agent dashboard or any other, you could setup a message in the conversation with the same content of `Instruction` to enforce the LLM to use the rag tool as well.

* Restart **Claude Desktop**.

* You will see two warnings on rag_tool configuration: they will disappear and will not cause any issue in activating the tool.

* Start a conversation. You should see a pop up that ask to allow the `rag` tool usage to answer the questions:

![Rag Tool](./images/rag_tool.png)

If the question is related to the knowledge base content stored in the vector store, you will have an answer based on that information. Otherwise, it will try to answer considering information on which has been trained the LLM o other tools configured in the same Claude Desktop.


## Make a remote MCP server the RAG Tool
## Run the RAG Tool by a remote MCP server

In `rag_base_optimizer_config_mcp.py`:

* Update the absolute path of your `optimizer_settings.json`. Example:
* Check if configuration is like this for the clients (`Remote client`) in the following lines, otherwise change as shown:

```python
rag.set_optimizer_settings_path("/Users/cdebari/Documents/GitHub/ai-optimizer-mcp-export/src/client/mcp/rag/optimizer_settings.json")
# Initialize FastMCP server
mcp = FastMCP("rag",host="0.0.0.0", port=9090) #Remote client
#mcp = FastMCP("rag") #Local
```

* Substitute `Local` with `Remote client` line:

```python
#mcp = FastMCP("rag", port=8001) #Remote client
mcp = FastMCP("rag") #Local
```
* Check, or change, according following lines of code:

* Substitute `stdio` with `sse` line of code:
```python
mcp.run(transport='stdio')
#mcp.run(transport='sse')
#mcp.run(transport='stdio')
#mcp.run(transport='sse')
mcp.run(transport='streamable-http')
```

* Start MCP server in another shell with:

```bash
uv run rag_base_optimizer_config_mcp.py
```


## Quick test
## Quick test via MCP "inspector"

* Run the inspector:

```bash
npx @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector@0.15.0
```

* connect the browser to `http://127.0.0.1:6274`
* connect to the linke report like this:

* set the Transport Type to `SSE`

* set the `URL` to `http://localhost:8001/sse`
```
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=1b40988bb02624b74472a9e8634a6d78802ced91c34433bf427cb3533c8fee2c
```

* test the tool developed.
* setup the `Transport Type` to `Streamable HTTP`
* test the tool developed, setting `URL` to `http://localhost:9090/mcp`.


## Claude Desktop setup

## Claude Desktop setup for remote/local server
Claude Desktop, in free version, not allows to connect remote server. You can overcome, for testing purpose only, with a proxy library called `mcp-remote`. These are the options.
If you have already installed Node.js v20.17.0+, it should work:

* replace `rag` mcpServer, setting in `claude_desktop_config.json`:
```json
{
"mcpServers": {
"remote": {
If you have already installed Node.js v20.17.0+, it should work.

* In **Claude Desktop** application, in `Settings/Developer/Edit Config`, get the `claude_desktop_config.json` to add the reference to the local MCP server for RAG in `streamable-http`:
```json
{
"mcpServers": {
...
,
"rag":{
"command": "npx",
"args": [
"mcp-remote",
"http://127.0.0.1:8001/sse"
]
}
}
}
```
* restart Claude Desktop.
"http://127.0.0.1:9090/mcp"
]
}
}
}
```


* In **Claude Desktop** application, in `Settings/General/Claude Settings/Configure`, under `Profile` tab, update fields like:

- `Full Name`
- `What should we call you`

and so on, putting in `What personal preferences should Claude consider in responses?`
the following text:

```
#INSTRUCTION:
Always call the rag_tool tool when the user asks a factual or information-seeking question, even if you think you know the answer.
Show the rag_tool message as-is, without modification.
```
This will impose the usage of `rag_tool` in any case.

* Restart **Claude Desktop**.

* You will see two warnings on rag_tool configuration: they will disappear and will not cause any issue in activating the tool.

* Start a conversation. You should see a pop up that ask to allow the `rag` tool usage to answer the questions:

![Rag Tool](./images/rag_tool.png)

If the question is related to the knowledge base content stored in the vector store, you will have an answer based on that information. Otherwise, it will try to answer considering information on which has been trained the LLM o other tools configured in the same Claude Desktop.

**NOTICE**: If you have any problem running, check the logs if it's related to an old npx/nodejs version used with mcp-remote library. Check with:
```bash
Expand Down
Loading