This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-mcp.git
The following commit(s) were added to refs/heads/main by this push:
new 63d9f76c docs(clients): add Codex setup guide (#242)
63d9f76c is described below
commit 63d9f76ce11a4ba662a2264f0fbd9b52d3abb4ad
Author: Aditya Parikh <[email protected]>
AuthorDate: Tue Oct 6 14:24:58 2026 -0400
docs(clients): add Codex setup guide (#242)
* docs(clients): add Codex setup guide
Document connecting OpenAI Codex CLI over STDIO and streamable HTTP,
with both the JAR and Docker image, including bearer-token auth for
secured HTTP. Link it from the README, the client index and the tutorial.
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
* docs(clients): add Codex troubleshooting for Access Denied
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
---------
Signed-off-by: Aditya Parikh <[email protected]>
Co-authored-by: Claude Sonnet 5.5 <[email protected]>
---
README.md | 5 +-
docs/clients/README.md | 1 +
docs/clients/codex.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++
docs/tutorial.md | 2 +-
4 files changed, 139 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 4c96bb35..4521e02e 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Just ask your AI assistant:
> *"Find sci-fi movies with 'star wars' in the title released after 2000, show
> me the genre breakdown, and sort by relevance."*
-This Spring AI [Model Context Protocol
(MCP)](https://modelcontextprotocol.io/) server exposes Solr operations as
tools that any MCP-compatible AI client (Claude Desktop, Claude Code, ChatGPT,
VS Code/Copilot, Cursor, JetBrains) can invoke.
+This Spring AI [Model Context Protocol
(MCP)](https://modelcontextprotocol.io/) server exposes Solr operations as
tools that any MCP-compatible AI client (Claude Desktop, Claude Code, Codex,
ChatGPT, VS Code/Copilot, Cursor, JetBrains) can invoke.
## Quick start
@@ -61,6 +61,7 @@ Add the server to your MCP client. For **Claude Desktop**,
edit
Using a different client, or want STDIO/HTTP/Docker options? See the
per-client guides:
**[Claude Desktop](docs/clients/claude-desktop.md)** ·
**[Claude Code](docs/clients/claude-code.md)** ·
+**[Codex](docs/clients/codex.md)** ·
**[ChatGPT](docs/clients/chatgpt.md)** (HTTP only) ·
**[VS Code / Copilot](docs/clients/vs-code.md)** ·
**[Cursor](docs/clients/cursor.md)** ·
@@ -157,7 +158,7 @@ Running in **HTTP mode** — OAuth2, CORS, and the
`HTTP_SECURITY_ENABLED` toggl
## Documentation
**Using it**
-- [Quick start](#quick-start) · [Client setup](docs/clients/) — Claude
Desktop, Claude Code, ChatGPT, VS Code, Cursor, JetBrains, MCP Inspector
+- [Quick start](#quick-start) · [Client setup](docs/clients/) — Claude
Desktop, Claude Code, Codex, ChatGPT, VS Code, Cursor, JetBrains, MCP Inspector
- [Tutorial: your first collection](docs/tutorial.md) — index a dataset twice,
schemaless then with a designed schema, and see why field types matter
- [Observability](docs/observability.md) — OpenTelemetry traces, metrics, logs
- Security: [Deployment model
(single-tenant)](docs/security/deployment-model.md) · [STDIO
model](docs/security/stdio.md) · [HTTP model](docs/security/http.md) · OAuth2
setup: [Auth0](docs/security/auth0.md) · [Keycloak](docs/security/keycloak.md)
diff --git a/docs/clients/README.md b/docs/clients/README.md
index e89ae033..0ce43bf0 100644
--- a/docs/clients/README.md
+++ b/docs/clients/README.md
@@ -9,6 +9,7 @@ server's streamable HTTP endpoint at
`http://localhost:8080/mcp`).
|--------|-------|
| Claude Desktop | [claude-desktop.md](claude-desktop.md) |
| Claude Code | [claude-code.md](claude-code.md) |
+| Codex | [codex.md](codex.md) |
| ChatGPT (HTTP only) | [chatgpt.md](chatgpt.md) |
| VS Code / GitHub Copilot | [vs-code.md](vs-code.md) |
| Cursor | [cursor.md](cursor.md) |
diff --git a/docs/clients/codex.md b/docs/clients/codex.md
new file mode 100644
index 00000000..517750e7
--- /dev/null
+++ b/docs/clients/codex.md
@@ -0,0 +1,134 @@
+# Codex
+
+[OpenAI Codex CLI](https://developers.openai.com/codex/mcp) supports MCP
servers over **STDIO** and **streamable HTTP**. Servers live in
`~/.codex/config.toml` (or a project-scoped `.codex/config.toml` in a trusted
project) under `[mcp_servers.<name>]`, and you can manage them with `codex mcp
add`. The Codex IDE extension shares the same configuration.
+
+The four ways to run Solr MCP with Codex:
+
+| | JAR | Docker |
+|---|---|---|
+| **STDIO** | Codex launches `java -jar …` | Codex launches `docker run -i …` |
+| **HTTP** | You run `java -jar …` with `PROFILES=http` | You run `docker run
-p 8080:8080 …` with `PROFILES=http` |
+
+***
+
+## CLI Syntax ##
+
+The general form of `codex mcp add` is:
+
+```bash
+codex mcp add <name> [--env KEY=VALUE]... -- <command> [args...] # STDIO
+codex mcp add <name> --url <url> [--bearer-token-env-var VAR] # HTTP
+```
+
+For a **STDIO** server, pass any `--env KEY=VALUE` options (repeatable) before
the `--`, then the launch command after it. `--env` is only valid for STDIO
servers; `--bearer-token-env-var` only for HTTP ones.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### CLI ###
+
+```bash
+# JAR
+codex mcp add solr-mcp \
+ --env SOLR_URL=http://localhost:8983/solr/ \
+ -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Docker (local image — build first with ./gradlew jibDockerBuild)
+codex mcp add solr-mcp \
+ -- docker run -i --rm -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+### `config.toml` ###
+
+Equivalent to the commands above; add to `~/.codex/config.toml`:
+
+**JAR:**
+
+```toml
+[mcp_servers.solr-mcp]
+command = "java"
+args = ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"]
+
+[mcp_servers.solr-mcp.env]
+SOLR_URL = "http://localhost:8983/solr/";
+```
+
+**Docker (local image):**
+
+```toml
+[mcp_servers.solr-mcp]
+command = "docker"
+args = ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
`args` array (or `--add-host=host.docker.internal:host-gateway` before the
image name in the CLI form).
+
+If the server is slow to start (a cold JVM, or Docker pulling the image on
first use), raise the handshake limit with `startup_timeout_sec = 60` in the
same table. Pull the image once beforehand to avoid it.
+
+***
+
+## HTTP Mode ##
+
+Start the server in HTTP mode first, in a terminal you keep open. For a local,
unsecured server set `HTTP_SECURITY_ENABLED=false` — HTTP mode requires OAuth2
by default (see the [HTTP security model](../security/http.md)):
+
+```bash
+# JAR
+PROFILES=http HTTP_SECURITY_ENABLED=false SOLR_URL=http://localhost:8983/solr/
\
+ java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Docker (local image)
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http -e HTTP_SECURITY_ENABLED=false \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+Either way the endpoint is `http://localhost:8080/mcp`; Codex does not care
which one is behind it. Then:
+
+### CLI ###
+
+```bash
+codex mcp add solr-mcp --url http://localhost:8080/mcp
+```
+
+### `config.toml` ###
+
+```toml
+[mcp_servers.solr-mcp]
+url = "http://localhost:8080/mcp";
+```
+
+Verify with `codex mcp list`, or `/mcp` inside a Codex session. The server
must already be running when Codex starts.
+
+### Secured HTTP (OAuth2) ###
+
+A secured server never answers an anonymous `/mcp` request with `401`, so
Codex will not start an OAuth login on its own — give it the access token
explicitly. Export the token in the shell that launches Codex and name the
variable:
+
+```bash
+export SOLR_MCP_TOKEN=<access-token>
+codex mcp add solr-mcp --url http://localhost:8080/mcp --bearer-token-env-var
SOLR_MCP_TOKEN
+```
+
+```toml
+[mcp_servers.solr-mcp]
+url = "http://localhost:8080/mcp";
+bearer_token_env_var = "SOLR_MCP_TOKEN"
+```
+
+The `aud` claim of the token must match the URL Codex dials. Codex re-reads
the variable each time it starts, so restart it after refreshing an expired
token. See the [HTTP security model](../security/http.md) for server-side
OAuth2 setup, and the [Keycloak](../security/keycloak.md) and
[Auth0](../security/auth0.md) guides for obtaining a token.
+
+### Troubleshooting ###
+
+**`codex mcp list` shows the server and Codex finds its tools, but every call
returns `Access Denied`.** The server is running with security on (the default
in HTTP mode) and Codex is not sending a token. This is not a protocol-version
problem — the server negotiates every MCP version. Either restart the server
with `HTTP_SECURITY_ENABLED=false` for local use, or follow the secured-HTTP
steps above. Confirm which one you have without involving Codex:
+
+```bash
+curl -s -X POST http://localhost:8080/mcp \
+ -H 'Content-Type: application/json' -H 'Accept: application/json,
text/event-stream' \
+ -d
'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list-collections","arguments":{}}}'
+```
+
+`Access Denied` in the result means security is on.
diff --git a/docs/tutorial.md b/docs/tutorial.md
index d2bb8544..0f4a4797 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -282,7 +282,7 @@ names via your client's tool inspector before assuming the
data is wrong.
## Where to go next
-- **[Client setup guides](clients/)** — Claude Desktop, Claude Code, ChatGPT,
VS Code /
+- **[Client setup guides](clients/)** — Claude Desktop, Claude Code, Codex,
ChatGPT, VS Code /
Copilot, Cursor, JetBrains, MCP Inspector
- **[Security](security/)** — the deployment model, the HTTP transport, and
OAuth2
setup with Auth0 or Keycloak
