Skip to main content

Knowledge & MCP

RAG pipeline​

Upload PDFs and ask questions about their content using vector similarity search.

RAG needs an embeddings offering in your model offering catalog (model_offerings.jsonc) -- author it with the in-app Model Settings screen, chatwalaau models add, or by hand:

{
  "id": "embed",
  "provider": "azure-openai",
  "operations": ["embeddings"],
  "model_ref": "text-embedding-3-small"
}

The pipeline knobs remain plain .env values (they are not model routing):

CHROMA_DIR=.chroma
RAG_COLLECTION_NAME=default
RAG_TOP_K=5
RAG_CHUNK_SIZE=800
RAG_CHUNK_OVERLAP=200
# RAG_CHUNK_MIN_SIZE=200   # unset -> RAG_CHUNK_SIZE // 4; 0 disables tail-merge

With no embeddings offering, RAG search and ingest return an actionable message telling you to add one (the app otherwise starts normally).

Workflow:

  1. + -> Attach PDF to upload a document
  2. Submit an ingest job -- either ask the agent "Please ingest this document", or open the Pipelines portal (below) and submit a rag-ingest job with the file path
  3. The pipeline job runs: PDF parsing -> chunking -> embedding -> ChromaDB storage
  4. Ask: "What does the document say about X?"
  5. The agent answers with source citations (filename, page)

Highlights: file-based ChromaDB storage, a singleton embedding client (one credential + TLS handshake per process), overlap chunking with tail-merge, metadata-based citation, automatic de-duplication on re-ingest, and PDF file cards in chat. Ingestion runs on the Pipeline Jobs engine (below), which is built in.

Pipeline Jobs​

Data-processing tasks (RAG ingestion today; more job types over time) run on an in-process pipeline engine with a dedicated management screen. Open the Pipelines icon in the sidebar footer (next to Declarative Agents) to:

  • Submit a job from a job-type form (e.g. rag-ingest with a PDF path)
  • Watch live progress with a progress bar and status
  • Cancel a running job or delete a finished one
  • Review run history -- each execution keeps a captured log you can open

It is on by default (PIPELINE_ENABLED=true). Pipeline jobs are curated in-process job types (no shell, no CODING_ENABLED) -- distinct from the Cron Scheduler, which runs scheduled scripts and is off by default. Configuration:

# Pipeline Jobs (in-process data-processing engine)
PIPELINE_ENABLED=true
PIPELINE_JOBS_DIR=.pipeline          # per-job JSON + output/{job}/{run}/ run logs
PIPELINE_OUTPUT_MAX_BYTES=1048576    # per-run captured-log cap
PIPELINE_MAX_CONCURRENT_JOBS=2

The agent can also manage jobs via the manage_pipeline tool (submit / list / get / cancel / delete); the agent tool and the REST API (/api/pipeline/*) share the same engine and store, so the chat and the portal never diverge.

MCP integration​

Connect external tools via the Model Context Protocol using the Claude Desktop-compatible config. ChatWalaʻau ships a bundled default (mcp_servers.default.jsonc) and prefers an operator override (mcp_servers.jsonc, gitignored) -- no manual copy on first run.

# Optional: defaults to mcp_servers.jsonc; set empty to disable MCP.
# MCP_CONFIG_FILE=mcp_servers.jsonc
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}
  • JSONC -- // and /* */ comments are stripped; strict JSON is accepted unchanged, so existing Claude Desktop / Claude Code / Cursor configs reuse
  • stdio servers (with command) are spawned; HTTP/SSE servers (with url) are connected to
  • MCP tools appear alongside built-in tools and show a Plug icon
  • Server lifecycle is managed automatically (with zombie-process prevention)
  • Optional per-server fields: "load_prompts": true (for servers implementing prompts/list; default false), "load_tools": false, "request_timeout": 30

Manage MCP tools at runtime​

A large MCP surface costs input tokens on every turn (each tool's name, description, and schema are sent to the model). The MCP Tools manager lets you disable the tools you are not using -- no config edit, no restart.

  • Open it from the Plug (MCP) icon in the chat input controls row. The icon is always shown when the manager endpoint is reachable; if no servers are connected yet the modal shows an empty state with your config path and a Reload button.
  • The modal opens at ~90% of the window with a left list of servers and a right detail pane. Toggle a whole server, or individual tools (tool descriptions are shown when the server provides them).
  • Save is enabled only after you change something. Saving asks for confirmation, then shows a "rebuilding agents" indicator while the change is applied; closing with unsaved changes prompts you to Save or Discard.
  • Saving rebuilds the agents so your next message uses only the selected tools. The selection is in-memory only -- a restart re-enables every MCP tool.
  • Reload (footer + empty state) re-parses mcp_servers.jsonc and fully reconnects the servers, then rebuilds the agents -- so a server you added or edited in the config is picked up without a restart. Reload asks for confirmation and shows the same blocking indicator. A server that is configured but not connected yet appears with a disabled toggle and a "Reload to apply" hint until you reconnect it.
  • The manager is an operator function gated by the same authentication as other write endpoints (localhost is exempt). It applies to all users of that server.

MCP Apps​

When an MCP tool declares a _meta.ui resource, its HTML View renders as interactive UI inside the chat message, in a secure double-iframe sandbox.

# MCP_APPS_SANDBOX_PORT=8081   # optional sandbox proxy port
  • Double-iframe sandbox -- Views run on a separate origin with no access to host DOM, cookies, or storage; CSP blocks external resources by default
  • Auditable -- all View-to-Server interaction is proxied through the Host
  • Display modes -- inline and fullscreen; session persistence stores View HTML for reload
  • Progressive enhancement -- tools work as text when UI is unavailable

No configuration needed; MCP Apps activates automatically and the sandbox proxy starts alongside MCP servers.