stack

Single-binary CLI tool that orchestrates the MCP server stack for local development, integration testing, and RAG dataset building. Reads stack.toml, derives all component configuration from it, and drives podman/docker compose to start or stop the full stack.

Quick Start

1. Prerequisites

Install Go, Podman (or Docker), and uv, then:

cd installers
make submodules       # clones all git submodules
make prereqs          # installs huggingface_hub CLI + podman-compose
cd ..
make build            # produces ./bin/stack + rag-mcp-server tools

2. Local development setup (optional)

Skip this section if you are connecting to a shared team development server that already provides PostgreSQL, llama-server, and Keycloak. Jump to Configure and start the stack and point stack.toml at the shared services.

PostgreSQL + pgvector:

cd installers
make install-postgres # installs PostgreSQL and pgvector (macOS or Linux)
make prep-database    # creates role, database, enables pgvector (reads from stack.toml)
cd ..

Inference servers (embedding + reranker):

cd installers
make build-llama      # builds llama-server from the llama.cpp submodule
make download-models  # downloads all required GGUF models
cd ..
make run-inference-servers  # starts both servers in the background

Keycloak is started automatically by make up when "keycloak" is in your stack.toml profiles. No manual setup is needed.

3. Configure and start the stack

cp stack.toml.example stack.toml
$EDITOR stack.toml    # adjust passwords; on a team server, point to shared services

make up               # generates configs, creates network, starts all services
make ingest           # ingest documents into the vector database

Wait for make up to report all services healthy. The MCP endpoint is now listening at http://localhost:15080/mcp.

3. Get a JWT token

Every request to the MCP server requires a valid JWT. The stack includes Keycloak (default) or Logto as an OIDC provider. Keycloak is fully automated -- realm, clients, and audience are provisioned on first start.

# With the default Keycloak config from stack.toml.example:
export OIDC_PROVIDER=keycloak
export KEYCLOAK_ISSUER=http://localhost:8080/realms/dev
export KEYCLOAK_CLIENT_ID=my-app
export KEYCLOAK_CLIENT_SECRET=changeme-dev-secret

TOKEN=$(./rag-mcp-server/scripts/get-token.sh)
echo "$TOKEN"

4. Test with curl

# Initialize MCP session
SESSION=$(curl -s -X POST http://localhost:15080/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  -D - -o /dev/null 2>&1 | grep -i mcp-session-id | tr -d '\r' | awk '{print $2}')

# Send initialized notification
curl -s -X POST http://localhost:15080/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# Search documents
curl -s -X POST http://localhost:15080/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_documents","arguments":{"query":"how do I reset my password","limit":5}}}' | jq .

5. Connect from Claude Code

Claude Code supports MCP servers over Streamable HTTP. Because this server requires JWT authentication, you need to supply a token via headers.

Option A: Dynamic token refresh with headersHelper (recommended)

Create a script that outputs auth headers as JSON. Claude Code calls it automatically before each MCP request, so tokens are alwa

... View full README on GitHub