Skip to main content

Generic RAG MCP server

Every Generic RAG application is also an MCP server, with five tools and one resource over its documents. Agents use them to list, read, search, and cite the documents, or to get an answer. This reference is for developers who connect a Quick App or another MCP client to a Generic RAG application. It is checked against backend 0.3.3, which locks FastMCP 3.4.2.

Endpoint​

Clients call the server through DIAL Core, at POST /v1/deployments/<application>/mcp, with their DIAL credentials. DIAL Core forwards each message to the backend's /mcp/streamable-http with a per-request key and the application's ID.

  • Transport. Streamable HTTP, without sessions. The backend builds the tool list for each request.
  • Registration. The type needs dial:applicationTypeMcp with dial:forwardPerRequestKey set to true. See Register the application type.
  • Application ID. <application> is the application's name in the DIAL Core configuration, or applications/<bucket>/<name> for an application in a bucket.

The upstream guide notes that older DIAL Core versions serve the endpoint at /v1/toolset/<application>/mcp.

Tools​

ToolArgumentsResult
list_documentsmetadata_filter, offset (default 0), limit (default 25), and newest_first (default true)A page of documents, each with id, title, number_of_pages, and the filterable metadata fields, plus total_count, offset, and limit
get_pagesdocument_id, page_start, page_end, and type: text, image, or both (the default)For each page in the range: a [Document <id>, Page <n>] label, the page's text, and the page image
get_citation_urldocument_idsA map of document IDs to links the caller can open
retrieve_text_chunksquery, document_ids, and metadata_filterThe retrieved text chunks, each with document_id, chunk_id, text, page_number, and metadata
rag_searchquery, document_ids, and metadata_filterThe answer, with citations as [Document <id>, Page <n>]. "No references found" is added when it cites nothing.
  • list_documents. With mcp.newest_sort, the list is sorted from newest to oldest, and newest_first: false reverses it. Without it, the order is arbitrary, the tool's description says so, and newest_first is hidden.
  • get_pages. A call returns at most MCP_GET_PAGES_LIMIT pages, 10 by default. Images come only from page images, which a page_extractor parser produces.
  • get_citation_url. Copies each document to the caller's appdata folder and returns the copy's link. It's the only tool that isn't marked read-only.
  • retrieve_text_chunks. Runs the application's retriever and returns text chunks only. metadata holds the fields marked enable_in_mcp_retrieve_chunks, or all fields when none is marked.
  • rag_search. Runs the application's retriever and the default generator, whatever generator the application sets. The description of query asks for one question per call.

document_ids restricts the search to these documents. metadata_filter is one metadata filter, ignored when document_ids is set.

Resource​

documents://metadata/{document_ids} returns the stored metadata of documents, as a JSON object keyed by document ID. document_ids is a comma-separated list of IDs, such as 1,5,9, with no spaces. IDs the channel doesn't have are left out.

Schemas per application​

The tool list differs between applications, because the backend shapes it from each application's configuration:

  • metadata_filter lists the application's filterable fields, narrowed by mcp.filterable_fields. A field with values in use accepts only those values.
  • The result of list_documents describes the application's filterable fields.
  • newest_first appears only with mcp.newest_sort.

Connect a client​

  • A Quick App. Add the application as a dial-app Toolset.
  • Deep Research. Configure a generic_rag source with this application's deployment ID, citation tool, and metadata resource. See Deep Research application properties.
  • An MCP client outside DIAL. Point it at the DIAL Core endpoint with an api-key header. For example, in a client that reads an mcpServers file:
{
  "mcpServers": {
    "generic-rag": {
      "type": "http",
      "url": "https://<DIAL_HOST>/v1/deployments/<APPLICATION_ID>/mcp",
      "headers": {
        "api-key": "<DIAL_API_KEY>"
      }
    }
  }
}

Further reading​