Okp Mcp

okp-mcp

[](https://github.com/rhel-lightspeed/okp-mcp/actions/workflows/ci.yml) [](https://scorecard.dev/viewer/?uri=github.com/rhel-lightspeed/okp-mcp) [](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/)

MCP server for the Red Hat Offline Knowledge Portal (OKP). Bridges LLM tool calls to the OKP Solr index so agents can search RHEL documentation, CVEs, errata, solutions, and articles.

Quickstart

Install dependencies:

uv sync

Run locally (stdio transport, default):

uv run okp-mcp

Run with HTTP transport:

uv run okp-mcp --transport streamable-http --port 8000

Configuration

Settings come from CLI arguments and MCP_* environment variables. CLI args take precedence.

| Setting | Env var | Default | Description | |---------|---------|---------|-------------| | --transport | MCP_TRANSPORT | streamable-http | stdio, sse, or streamable-http | | --host | MCP_HOST | 0.0.0.0 | Bind address for HTTP transports | | --port | MCP_PORT | 8000 | Bind port for HTTP transports | | --log-level | MCP_LOG_LEVEL | INFO | Python log level | | --solr-url | MCP_SOLR_URL | http://localhost:8983 | Base URL of the Solr instance | | --glitchtip-dsn | MCP_GLITCHTIP_DSN | unset | Optional GlitchTip/Sentry DSN for exception reporting |

Run okp-mcp --help for the full list.

Running Locally

Run the OKP Solr index and MCP server together using a podman pod.

Prerequisites

• Podman installed
• Authenticated to registry.redhat.io (podman login registry.redhat.io)
• An OKP access key from

1. Create a pod

The pod groups both containers into a shared network namespace so they communicate via localhost. Ports are exposed at the pod level.

podman pod create --name okp -p 8983:8983 -p 8000:8000

2. Start the OKP Solr index

podman run -d --pod okp --name redhat-okp \
  -e ACCESS_KEY= \
  -e SOLR_JETTY_HOST=0.0.0.0 \
  registry.redhat.io/offline-knowledge-portal/rhokp-rhel9:latest

The first start downloads and indexes content (~10 GB image, may take several minutes). Watch progress with:

podman logs -f redhat-okp

Wait until you see Started Solr server on port 8983. Subsequent starts of the same container (podman pod stop okp / podman pod start okp) are faster because the index is cached. Removing the pod (podman pod rm -f okp) deletes the container and its index — the next podman run will re-index the content. To persist the index across recreations, add a named volume: -v okp-solr-data:/opt/solr/server/solr/portal/data.

3. Start the MCP server

podman run -d --pod okp --name okp-mcp \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_SOLR_URL=http://localhost:8983 \
  quay.io/redhat-user-workloads/rhel-lightspeed-tenant/rhel-knowledge-bridge

4. Verify

> Note: The -4 flag forces IPv4. On some systems (e.g. Fedora 43), localhost resolves to ::1 (IPv6), which causes a "Connection reset by peer" error. Use -4 to avoid this.

Confirm Solr has data:

curl -s -4 "http://localhost:8983/solr/portal/select?q=*:*&rows=0" | python3 -m json.tool

You should see numFound with a large number of documents (600k+).

Confirm the MCP server responds:

curl -s -4 -N -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'

You should see a response with serverInfo.name: "RHEL OKP Knowledge Base".

Cleanup

podman pod rm -f okp

Alternative: systemd quadlets

For a systemd-managed setup with automatic restart, boot persistence, and journald logging, see [quadlet/README.md](quadlet/README.md).

Alternative: podman-compose

A podman-compose.yml is included for development use. It builds from source and is useful for local iteration, but note that podman-compose is not supported on RHEL.

OKP_ACCESS_KEY= podman-compose up -d

Development

Install dev dependencies and pre-commit hooks:

uv sync --group dev
pre-commit install

Run the full CI suite locally:

make ci

Individual targets:

make lint        # ruff check
make format      # ruff format
make typecheck   # ty check
make radon       # cyclomatic complexity gate (A/B only)
make test        # pytest with coverage

Functional Tests

Functional test scenarios are defined in tests/functional_cases.py. They are gated behind the functional pytest marker and deselected by default. Run them with uv run pytest -m functional -v (requires a running Solr instance).

License

See [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rhel-lightspeed
• Source: rhel-lightspeed/okp-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.