Skip to content

Commit cdb8cbf

Browse files
ldemarchisldemarchis
authored
Added MCP Client Configuration docs (#499)
1 parent 7385044 commit cdb8cbf

1 file changed

Lines changed: 224 additions & 0 deletions

File tree

  • docs/content/advanced/MCP Client Configuration

‎docs/content/advanced/MCP Client Configuration/_index.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
+++
2+
title = 'MCP Client Configuration'
3+
weight = 25
4+
url = '/advanced/mcp-client-configuration/'
5+
+++
6+
7+
<!--
8+
Copyright (c) 2024, 2026, Oracle and/or its affiliates.
9+
Licensed under the Universal Permissive License v1.0 as shown at http://oss.oracle.com/licenses/upl.
10+
11+
spell-checker: ignore apikey claude cline httpx json langgraph mcpServers npx sqlcl streamable
12+
-->
13+
14+
The {{% full_app_ref %}} exposes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server at `/mcp`. External MCP clients can connect to this endpoint and use the tools, prompts, and resources registered by the {{% short_app_ref %}}, including Vector Search tools and SQLcl tools when NL2SQL is configured.
15+
16+
The recommended way to configure a client is to copy the generated JSON from the **MCP Configuration** page or request the client-specific configuration from the API Server.
17+
18+
## Prerequisites
19+
20+
1. Start the {{% short_app_ref %}} API Server.
21+
2. Retrieve or configure the API key. If `AIO_API_KEY` was not set before startup, get the generated key from the [API Server]({{% relref "/client/api_server" %}}) page.
22+
3. Confirm that the MCP server is healthy:
23+
24+
```bash
25+
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/healthz
26+
```
27+
28+
4. If you need Vector Search, split and embed documents first. See [Split & Embed]({{% relref "/client/tools/split_embed" %}}).
29+
5. If you need NL2SQL tools, install SQLcl and configure a database. See [MCP Server]({{% relref "/client/configuration/mcp" %}}).
30+
31+
## Get the Generated Configuration
32+
33+
In the UI, open **Configuration -> MCP Server**, expand **Client Configuration**, and select the target client:
34+
35+
- **Cline for VS Code**
36+
- **LangGraph**
37+
- **Claude Desktop**
38+
39+
You can also request the same JSON from the API Server:
40+
41+
```bash
42+
curl -H "X-API-Key: $AIO_API_KEY" \
43+
"http://localhost:8000/mcp/client-config?client=cline" | jq .
44+
```
45+
46+
Supported client values include:
47+
48+
| Client | Query value | Notes |
49+
|--------|-------------|-------|
50+
| Cline for VS Code | `cline` | Streamable HTTP configuration with a `type` field |
51+
| LangGraph | `langgraph` | Streamable HTTP configuration without the `type` field |
52+
| Claude Desktop | `claude-desktop` | Local `mcp-remote` bridge configuration |
53+
54+
Use the generated JSON as the source of truth. It includes the correct URL, path prefix, and `X-API-Key` header for the running API Server.
55+
56+
## Cline for VS Code
57+
58+
Cline can connect to hosted MCP servers over Streamable HTTP. Get the Cline configuration:
59+
60+
```bash
61+
curl -H "X-API-Key: $AIO_API_KEY" \
62+
"http://localhost:8000/mcp/client-config?client=cline" | jq .
63+
```
64+
65+
Example output:
66+
67+
```json
68+
{
69+
"mcpServers": {
70+
"oracle-ai-optimizer": {
71+
"transport": "streamable-http",
72+
"url": "http://localhost:8000/mcp",
73+
"headers": {
74+
"X-API-Key": "replace-with-your-api-key"
75+
},
76+
"type": "streamableHttp"
77+
}
78+
}
79+
}
80+
```
81+
82+
To add it in Cline:
83+
84+
1. Open VS Code.
85+
2. Open the Cline panel.
86+
3. Click the **MCP Servers** icon.
87+
4. Open the **Configure** tab.
88+
5. Click **Configure MCP Servers**.
89+
6. Add the `oracle-ai-optimizer` entry under `mcpServers`.
90+
7. Save the file and confirm that the Optimizer tools appear in Cline.
91+
92+
If you use the Cline remote-server form instead of editing JSON, use:
93+
94+
| Field | Value |
95+
|-------|-------|
96+
| Server Name | `oracle-ai-optimizer` |
97+
| Server URL | `http://localhost:8000/mcp` |
98+
| Transport Type | `Streamable HTTP` |
99+
| Header | `X-API-Key: <your API key>` |
100+
101+
## LangGraph
102+
103+
LangGraph MCP integrations expect the Streamable HTTP endpoint and authentication headers. Get the LangGraph-specific configuration:
104+
105+
```bash
106+
curl -H "X-API-Key: $AIO_API_KEY" \
107+
"http://localhost:8000/mcp/client-config?client=langgraph" | jq .
108+
```
109+
110+
Example output:
111+
112+
```json
113+
{
114+
"mcpServers": {
115+
"oracle-ai-optimizer": {
116+
"transport": "streamable-http",
117+
"url": "http://localhost:8000/mcp",
118+
"headers": {
119+
"X-API-Key": "replace-with-your-api-key"
120+
}
121+
}
122+
}
123+
}
124+
```
125+
126+
The LangGraph variant intentionally omits the `type` key. Use the `url` and `headers` values when creating a Streamable HTTP MCP client or when wiring the Optimizer MCP server into an AgentSpec/LangGraph workflow.
127+
128+
Minimal Python example:
129+
130+
```python
131+
import httpx
132+
from langchain_mcp_adapters.tools import load_mcp_tools
133+
from mcp.client.session import ClientSession
134+
from mcp.client.streamable_http import streamable_http_client
135+
136+
server_url = "http://localhost:8000/mcp"
137+
138+
async with httpx.AsyncClient(headers={"X-API-Key": "replace-with-your-api-key"}) as http_client:
139+
async with streamable_http_client(server_url, http_client=http_client) as (read, write, _):
140+
async with ClientSession(read, write) as session:
141+
await session.initialize()
142+
tools = await load_mcp_tools(session)
143+
```
144+
145+
## Claude Desktop
146+
147+
Claude Desktop typically starts MCP servers as local processes. For the Optimizer's remote HTTP endpoint, the generated configuration uses `mcp-remote` as a local bridge.
148+
149+
Get the Claude Desktop configuration:
150+
151+
```bash
152+
curl -H "X-API-Key: $AIO_API_KEY" \
153+
"http://localhost:8000/mcp/client-config?client=claude-desktop" | jq .
154+
```
155+
156+
Example output:
157+
158+
```json
159+
{
160+
"mcpServers": {
161+
"oracle-ai-optimizer": {
162+
"command": "npx",
163+
"args": [
164+
"-y",
165+
"mcp-remote",
166+
"http://localhost:8000/mcp",
167+
"--transport",
168+
"http-only",
169+
"--header",
170+
"X-API-Key: replace-with-your-api-key"
171+
]
172+
}
173+
}
174+
}
175+
```
176+
177+
To add it in Claude Desktop:
178+
179+
1. Install Node.js so that `npx` is available from the shell. Start the bridge between Claude Desktop and an HTTP/SSE/Streamable HTTP MCP endpoint. The default command to create this bridge to the AI Optimizer MCP would be the following:
180+
```bash
181+
npx mcp-remote http://localhost:8000/mcp \
182+
--transport http-only \
183+
--header "X-API-Key: replace-with-your-api-key" \
184+
--debug
185+
```
186+
2. Open **Claude Desktop -> Settings -> Developer -> Edit Config**.
187+
3. Add the `oracle-ai-optimizer` entry under `mcpServers` in `claude_desktop_config.json`.
188+
4. Save the file.
189+
5. Restart Claude Desktop.
190+
6. Start a new conversation and allow the Optimizer tools when Claude asks for permission.
191+
192+
## Verify the Connection
193+
194+
From the {{% short_app_ref %}} side, confirm that tools are registered:
195+
196+
```bash
197+
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/tools
198+
```
199+
200+
In the MCP client, ask a question that should require an Optimizer tool. For Vector Search, ask about content that exists in an embedded vector store. For NL2SQL, ask a database question only after SQLcl tools are visible.
201+
202+
## Troubleshooting
203+
204+
**`403 Forbidden`** — The `X-API-Key` header is missing or incorrect. Copy the JSON again from the MCP Configuration page or confirm `AIO_API_KEY`.
205+
206+
**Connection refused** — The API Server is not running, or the client is using the wrong host or port. The default local endpoint is `http://localhost:8000/mcp`.
207+
208+
**Tools are not visible** — Check the MCP health and tools endpoints:
209+
210+
```bash
211+
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/healthz
212+
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/tools
213+
```
214+
215+
**NL2SQL tools are missing** — Confirm that SQLcl is installed, the `sql` binary is on `PATH`, and at least one database is configured.
216+
217+
**Claude Desktop cannot start the server** — Confirm that `npx` is available to Claude Desktop. If needed, use the full path to `npx` in the `command` field.
218+
219+
## Related
220+
221+
- [MCP Server]({{% relref "/client/configuration/mcp" %}})
222+
- [Custom MCP Tools]({{% relref "/advanced/mcp" %}})
223+
- [IDE Integration]({{% relref "/advanced/ide_integration" %}})
224+
- [API Server]({{% relref "/client/api_server" %}})

0 commit comments

Comments
 (0)