Configuring the Document Index MCP server

The Document Index MCP server is a Model Context Protocol (MCP) server that lets PhariaAssistant Chat and other MCP clients search documents indexed in PhariaAI. It searches the collections requested by the client in parallel and merges the results into a single ranked list. Optionally, it can rerank the results with a dedicated reranker model.

The server is shipped with the PhariaAI Helm chart and enabled by default. This article describes how it is deployed and which configuration options are available, including reranking and metadata-based search filters.


How the server is deployed

The Document Index MCP server is packaged as the pharia-document-index-mcp subchart of the PhariaAI Helm chart and is installed by default. It is also registered automatically with PhariaAssistant Chat as a system-scoped MCP server (see Configuring additional MCP servers for PhariaAssistant Chat), so Chat can use it for document search without further configuration.

The server exposes the following HTTP endpoints:

Endpoint Description

/api/v1/mcp

MCP endpoint (Streamable HTTP transport)

/health, /status

Health and status checks

/metrics

Prometheus metrics

MCP clients can use the following tools:

Tool Description

search

Searches for relevant document chunks across one or more collections. In addition to the query and collections parameters, the tool accepts filter parameters that are generated from the configured filter schema; see Configuring metadata search filters.

list_collections

Lists the available document collections.

open_document

Retrieves the full content of a document by its URI, up to a configurable token limit.

Requests to the MCP endpoint are authenticated against PhariaIAM: clients must send a valid bearer token in the Authorization header. The /health, /status, and /metrics endpoints do not require authentication.

To verify that the server is running, port-forward the service and query the health endpoint:

kubectl -n <pharia-ai-install-namespace> port-forward svc/pharia-document-index-mcp 1337:1337

curl http://localhost:1337/health
# Should return: OK

Disabling the server

To disable the Document Index MCP server, disable both the deployment and its registration with PhariaAssistant Chat:

pharia-document-index-mcp:
  enabled: false

pharia-chat:
  jobInitMcpRegistry:
    mcpServers:
      document-index-mcp:
        enabled: false

General configuration

The server is configured through environment variables. In the PhariaAI Helm chart, you set them under pharia-document-index-mcp.env.values:

pharia-document-index-mcp:
  env:
    values:
      SCORE_THRESHOLD: '0.3'
      MAX_RESULTS: '10'
All entries under env.values must be strings. Quote numbers and booleans, for example '0.3' or 'true'.

The connection settings for the document index, the PhariaData API, and PhariaIAM (PHARIA_DOCUMENT_INDEX_URL and PHARIA_DATA_API_URL, each with an _EXTERNAL counterpart, and PHARIA_IAM_URL) are wired automatically from the global PhariaAI configuration; you do not need to set them yourself.

Search backends

The server supports two search backends, selected with SEARCH_STORES_ENABLED:

  • Search stores (SEARCH_STORES_ENABLED=true): searches the search stores of the PhariaData API. This is the default in current PhariaAI versions, controlled by the global.searchStoresEnabled Helm value.

  • Document index (SEARCH_STORES_ENABLED=false): queries the document index service directly. The DI_INDEX_NAME and COLLECTION_NAMESPACE variables select which index and namespace are searched.

Search settings

The following variables control the search behavior:

Variable Description Default

MAX_RESULTS

Maximum number of results returned by a search. When reranking is enabled, it also bounds the candidate pool that is passed to the reranker: up to this many candidates in total on the document index backend, up to this many per collection on the search stores backend. See Configuring reranking.

20

SCORE_THRESHOLD

Minimum relevance score for a search result to be returned. Results below this threshold are excluded. When reranking is enabled, RERANKER_SCORE_THRESHOLD is used instead.

0.2

DI_INDEX_NAME

Name of the document index to search. If a collection does not have this index assigned, the first index assigned to the collection is used instead. Only used by the document index backend. Can also be set with the pharia-document-index-mcp.documentIndex.indexName Helm value.

luminousBase-256-26-asymmetric-semantic-bm25

COLLECTION_NAMESPACE

Document index namespace in which collections are looked up. Only used by the document index backend.

Assistant

SEARCH_STORES_ENABLED

Selects the search backend; see Search backends. Set with the global.searchStoresEnabled Helm value rather than directly.

true (set by the PhariaAI Helm chart)

Configuring reranking

By default, search results are ranked by the retrieval scores of the search backend. Optionally, the server supports two-stage retrieval with a reranker model:

  1. The search backend retrieves candidates whose retrieval score is at least RERANKER_SCORE_THRESHOLD — up to MAX_RESULTS in total on the document index backend, or up to MAX_RESULTS per collection on the search stores backend.

  2. Each candidate is formatted with the document template (see Document templates) and sent to the reranker model, which scores it against the query. The document index backend sends at most RERANKER_MAX_CANDIDATES candidates; the search stores backend does not apply this cap.

  3. The results are reordered by reranker score, and the best RERANKER_TOP_K results are returned.

Reranking is transparent to MCP clients: the search tool keeps the same name and parameters. If the rerank request fails, the server logs a warning and returns the results in the original retrieval order, so search continues to work when the reranker is unavailable.

To use reranking, you need a reranker model (for example, qwen3-reranker-8b-hf) served behind a Jina/Cohere-style /v1/rerank endpoint, such as a vLLM deployment or a reranker model served through the PhariaInference API.

Enable reranking in the values of the PhariaAI Helm chart:

pharia-document-index-mcp:
  env:
    values:
      RERANKER_ENABLED: 'true'
      RERANKER_ENDPOINT: https://inference-api.example.com/v1/rerank
      RERANKER_DEFAULT_MODEL: qwen3-reranker-8b-hf
To rerank a larger candidate pool, increase MAX_RESULTS: it bounds how many candidates the first stage retrieves (in total on the document index backend, per collection on the search stores backend). MAX_RESULTS also applies to searches without reranking.

Reranker configuration reference

The following table describes all available reranker settings. The defaults listed are the values set by the PhariaAI Helm chart:

Variable Description Default

RERANKER_ENABLED

Enables two-stage retrieval with reranking.

false

RERANKER_ENDPOINT

URL of the rerank endpoint. Set this to the endpoint of your environment.

https://inference-api.customer.pharia.com/v1/rerank

RERANKER_DEFAULT_MODEL

Name of the reranker model, as it is registered at the rerank endpoint.

qwen3-reranker-8b-hf

RERANKER_TOP_K

Number of top-ranked results returned after reranking.

10

RERANKER_SCORE_THRESHOLD

Minimum retrieval score for a candidate to enter the reranking stage. Used instead of SCORE_THRESHOLD when reranking is enabled.

0.3

RERANKER_MAX_CANDIDATES

Hard limit on the number of candidates sent to the reranker in one request, to protect the reranker service. Only applied by the document index backend; the search stores backend does not enforce this limit.

256

RERANKER_RETRIEVER_TOP_N

Upper bound for RERANKER_TOP_K: a larger RERANKER_TOP_K is clamped to this value. It does not control the size of the retrieved candidate pool; that is MAX_RESULTS.

50

RERANKER_TIMEOUT_SECONDS

Timeout for rerank API calls, in seconds.

30

RERANKER_DEFAULT_INSTRUCTION

Task instruction that is inserted into the document template as $INSTRUCTION. Some models (for example, Nemotron rerankers) do not use an instruction; set it to an empty string in that case.

Given a web search query, retrieve relevant passages that answer the query

RERANKER_DOCUMENT_TEMPLATE

Template applied to each query-document pair before it is sent to the reranker; see Document templates.

Built-in Qwen3 ChatML template

RERANKER_AUTH_TYPE

How the server authenticates against the rerank endpoint: forward, bearer, basic, or none; see Authentication against the rerank endpoint.

forward

RERANKER_CREDENTIALS

Credentials for the rerank endpoint. Only used with RERANKER_AUTH_TYPE set to bearer (the token) or basic (username:password).

(empty)

Authentication against the rerank endpoint

The RERANKER_AUTH_TYPE variable supports the following modes:

  • forward: The bearer token of the requesting user is forwarded to the rerank endpoint. This is the default and works out of the box when the reranker model is served through the PhariaInference API, because the same PhariaIAM token is valid there.

  • bearer: A static bearer token, taken from RERANKER_CREDENTIALS, is sent with every rerank request.

  • basic: HTTP basic authentication; set RERANKER_CREDENTIALS to username:password.

  • none: No authentication headers are sent.

Document templates

Reranker models expect the query and document to be embedded into a model-specific prompt template.

vLLM does not automatically apply chat templates to /v1/rerank requests. Templates are only applied server-side if the vLLM server is started with the --chat-template option.

You have two options.

Server-side templating

If your vLLM deployment is started with --chat-template, disable client-side templating so that documents are sent as-is:

pharia-document-index-mcp:
  env:
    values:
      RERANKER_DOCUMENT_TEMPLATE: none

The values none, vllm, server, and disabled all disable client-side templating.

Client-side templating

The Document Index MCP server formats each document with the template from RERANKER_DOCUMENT_TEMPLATE before sending it to the rerank endpoint. The template must contain the placeholders $QUERY and $DOC, and can optionally contain $INSTRUCTION (replaced with RERANKER_DEFAULT_INSTRUCTION). A template without $QUERY or $DOC causes the server to fail at startup with a validation error.

If RERANKER_DOCUMENT_TEMPLATE is not set, a built-in template in the Qwen3 ChatML format is used, which is suitable for Qwen3 reranker models such as qwen3-reranker-8b-hf.

For other model families, set the template explicitly. For example, for mxbai-rerank-v2 models:

pharia-document-index-mcp:
  env:
    values:
      RERANKER_DEFAULT_MODEL: mxbai-rerank-base-v2
      RERANKER_DOCUMENT_TEMPLATE: "<|im_start|>system\nYou are Qwen, created by Alibaba Cloud. You are a helpful assistant.<|im_end|>\n<|im_start|>user\nquery: $QUERY\ndocument: $DOC\nYou are a search relevance expert who evaluates how well documents match search queries. For each query-document pair, carefully analyze the semantic relationship between them, then provide your binary relevance judgment (0 for not relevant, 1 for relevant).\nRelevance:<|im_end|>\n<|im_start|>assistant\n"

For Nemotron rerankers, which use a simple format without an instruction:

pharia-document-index-mcp:
  env:
    values:
      RERANKER_DEFAULT_MODEL: llama-nemotron-rerank-1b-v2
      RERANKER_DEFAULT_INSTRUCTION: ''
      RERANKER_DOCUMENT_TEMPLATE: "question:$QUERY \n \n passage:$DOC"
Use double-quoted YAML strings for templates, as shown above: YAML then turns the \n escape sequences into real line breaks, which is what the model expects.
Configurable reranker document templates can be used with PhariaAI version 1.260200 or later.

Configuring metadata search filters

The search tool can filter results by the metadata fields of the documents in your collections. The available metadata fields are determined when the documents are ingested. Filter parameters are defined in a filter schema and are exposed as explicitly typed parameters on the search tool, so that AI agents can discover them and use them correctly.

By default, a single filter parameter file_ids is available, which filters on the fileId metadata field. To offer filters that match the metadata of your own collections, define a custom filter schema with the pharia-document-index-mcp.filterSchema Helm value:

pharia-document-index-mcp:
  filterSchema:
    department:
      type: enum
      values:
        - Engineering
        - Sales
        - HR
      single: false
      description: "Filter by department(s)"
      example:
        - Engineering
    documentType:
      type: string
      single: true
      description: "Filter by document type"
      example: "policy"
    confidential:
      type: boolean
      description: "Filter to only include confidential documents"
      example: true
    fileId:
      type: string
      single: false
      description: "Filter results by specific file IDs"
      parameter_name: file_ids
Quote schema keys and string values that YAML would otherwise parse as booleans (on, off, yes, no, y, n, in any case). An unquoted on: key, for example, is rendered into the ConfigMap as the key "true", and the filter silently targets the wrong metadata field.

When filterSchema is set, the chart automatically:

  1. Creates a ConfigMap containing the schema as JSON.

  2. Mounts it into the pod at /etc/document-index-mcp/filter-schema/.

  3. Sets the FILTER_SCHEMA_PATH environment variable so that the server loads the schema at startup.

  4. Adds a checksum annotation so that pods restart when the schema changes.

The example above generates a search tool with the typed parameters department (list of the allowed values), documentType (string), confidential (boolean), and file_ids (list of strings), in addition to the built-in query and collections parameters.

The schema is validated when the server starts. A schema that is not well-formed — an unknown type, a duplicate parameter name, or a key that is not a valid metadata field name — causes the server to fail at startup with an error that describes the problem. An entry without a description does not fail validation: it is silently skipped and does not become a tool parameter.

Schema reference

Each key in the filter schema is the name of the metadata field to filter on, and by default also becomes the name of the tool parameter. The following field types are supported:

Type Tool parameter type (single: true) Tool parameter type (single: false)

string

string

list of strings

enum

one of the allowed values

list of the allowed values

boolean

boolean (always single)

-

Each schema entry supports the following fields:

Field Required Description

type

Yes

One of string, enum, or boolean.

description

Yes

Description of the parameter, shown to AI agents. Entries without a description are silently skipped and do not become tool parameters.

single

String and enum only

If true, the parameter accepts a single value; if false (the default), it accepts a list of values. Do not set it on boolean filters — they are always single, and setting the field there causes the server to fail at startup.

values

Enum only

The list of allowed values for an enum filter.

example

No

Example value(s), included in the generated tool documentation.

parameter_name

No

Name of the tool parameter exposed to AI agents; defaults to the schema key. Use this when the metadata field name and the desired parameter name differ, for example the singular metadata field fileId exposed as the list parameter file_ids. The name must be a valid Python identifier, must be unique within the schema, and must not collide with the reserved parameter names query, collections, and ctx.
The parameter_name field can be used with Document Index MCP server version 0.8.49 or later. To find the version your installation ships, check the pharia-document-index-mcp dependency of the PhariaAI Helm chart.
Each schema key is sent verbatim to the search backend as the metadata field to filter on. It is case-sensitive and is not checked against the actual metadata fields of your documents. A key that does not match a real metadata field (for example, file_id instead of fileId) does not cause an error — the filter simply matches nothing, and filtered searches silently return zero results. Verify the exact metadata field names of your documents before deploying a schema, and confirm afterwards that a filtered search returns results. One backward-compatibility exception: a key named file_ids without a parameter_name is automatically mapped to the fileId metadata field at startup.

Filter schemas and PhariaAssistant Chat

PhariaAssistant Chat manages the collections and file_ids parameters itself: it hides them from the model and fills them with the collections the user selected and the files the user attached. If your Document Index MCP server backs PhariaAssistant Chat and you deploy a custom filter schema, keep an entry for the fileId metadata field that is exposed as the file_ids parameter, as shown in the example above. All other filter parameters that you define are exposed to the Chat agent.

Verifying the filter schema

After deployment, confirm that the schema was loaded correctly.

A schema that fails validation crashes the server at startup, with the reason in the logs. First check that the pod is running:

kubectl -n <pharia-ai-install-namespace> get pods -l app=document-index-mcp-deployment

kubectl -n <pharia-ai-install-namespace> logs deployment/document-index-mcp

Then inspect the parameters of the generated search tool with the MCP Inspector, which handles the MCP session handshake for you:

kubectl -n <pharia-ai-install-namespace> port-forward svc/pharia-document-index-mcp 1337:1337

npx @modelcontextprotocol/inspector http://localhost:1337/api/v1/mcp

In the inspector, add your PhariaAI token as a bearer Authorization header, connect, and list the tools. The search tool shows your custom filter parameter names alongside query and collections.