Knowledge Retrieval and MCP Interoperability

Eneo has two ways to give a model access to an assistant’s knowledge: retrieve passages before the model runs and inject them into its prompt, or let a tool-capable model retrieve knowledge on demand. The on-demand path uses Eneo’s built-in, loopback Model Context Protocol (MCP) server. That server and administrator-configured external MCP servers then travel through the same proxy, naming, execution, result, and citation pipeline.

The short version

The setting on an assistant is knowledge_mode, with two values:

tool is conditional, not absolute. If the effective completion model does not support tool calling, Eneo automatically uses the injected path for that turn. An assistant therefore remains usable when a model is changed to one without tool support.

The built-in knowledge server is called loopback because the Eneo backend hosts its Streamable HTTP endpoint and also connects to that endpoint as an MCP client during a completion. This is an intentional adapter around Eneo’s own authorized services; it is not a second knowledge store and it does not send knowledge to a separate internal database.

Configure material in the assistant editor

The Assistentens material (Assistant material) section brings persistent file attachments and existing knowledge selectors together. Bilagor (Attachments) contains all attached files and the file uploader. Each file shows whether it is loaded before every answer or opened on demand; changing its reading mode does not move it out of Attachments.

Below the attachments and uploader, Organisationskunskap (Organization knowledge) contains sources owned by the organization space and Kunskap (Knowledge) contains every other source the space can use. Organization identity comes from the current space’s API response, independently of whether the user can open the organization space. When organization identity is unavailable, all sources appear in Knowledge.

The available options and selected sources use the same ownership classification. Every selected source remains visible and removable, including when its embedding model is disabled. The knowledge summary states whether searches run on demand or before every answer. These sections describe ownership; they do not grant access or change sharing permissions.

Use Ändra (Change) on a file to choose between Öppna vid behov (Open when needed) and Läs in inför varje svar (Load before every answer). The editor explains when the selected model, file type, stored original or deployment prevents on-demand access. Changing the model does not overwrite the saved file preference.

Hantering av material (Material handling) shows the knowledge search timing and chat-document handling controls directly, without a collapsed section. These remain independent: the knowledge setting controls searches for relevant passages, the chat setting controls user-uploaded documents, and each persistent attachment has its own setting. Rules, tone and procedures are configured in Prompt or Skills, both under Instruktioner (Instructions).

This organization does not change knowledge uploads, extraction, indexing or the assistant save flow. Newly uploaded assistant attachments default to opening on demand. When on-demand access is unavailable, their content is loaded upfront instead. Existing attachments retain their saved reading mode. Chat document text is still included directly, and knowledge still uses injected retrieval unless configured otherwise. On-demand file attachments are not automatically indexed as knowledge.

The Fast kontext (Fixed context) meter estimates prompt text and directly loaded attachments. It is not a total request estimate: chat history, skills, tool definitions, references and retrieved content also consume context. Including content does not guarantee the assistant will follow it.

Keep four concepts separate

Several things are called “knowledge” or “integration” in normal conversation, but they have different roles in the architecture.

An integration knowledge source is normalized into the same searchable knowledge abstraction as collections and websites. It is searched by injected retrieval or by the built-in knowledge MCP tools. An external MCP server is a live tool provider. The two can coexist, but attaching one does not implicitly attach the other.

Inject mode

Inject mode is Eneo’s original retrieval-augmented generation path and the compatibility path for models without tool calling.

Turn lifecycle

1. Eneo combines the current question with the preceding question-and-answer history to form the semantic search input.
2. It searches every knowledge source attached to the assistant: collections, websites, and integration knowledge.
3. The configured embedding model is selected from the attached sources and used for semantic search.
4. Retrieved chunks are admitted to the prompt within a bounded knowledge share of the model context window. Conversation history is reduced as needed to leave room for those chunks.
5. The model receives the selected text before it starts answering. The retrieved documents are also retained as answer references.

The search happens even for a greeting or a follow-up that does not need knowledge. Conversely, it happens only once before generation: the model cannot rephrase a weak query, split a multi-part question into several searches, or open the rest of a document during that turn.

Retrieval versions and relevance

The legacy retrieval version asks for up to 30 chunks and uses autocut to trim the low-relevance tail. The newer path derives a candidate count from the model’s input window and then fits results into the prompt budget. Deployments may set INJECT_KNOWLEDGE_MIN_SCORE to discard injected chunks below a cosine similarity threshold. It is unset by default because score distributions vary between embedding models.

When inject mode is a good fit

• The selected model cannot call tools.
• Every turn should get one predictable retrieval pass.
• The model or provider has unreliable tool-use behavior.
• Latency predictability matters more than iterative retrieval.
• The assistant has a small, focused corpus and questions are usually direct.

Its main cost is eager context use: passages are added before Eneo knows whether the model needs them. Large retrieved contexts also leave less room for conversation history and instructions.

Tool mode

Tool mode moves retrieval control into the model’s reasoning loop. Eneo puts a short catalog of the assistant’s source names into the prompt, but keeps source content behind four built-in tools:

The knowledge__ prefix is added by the shared MCP proxy. The unprefixed MCP tool names are search_knowledge, read_source, describe_source, and list_knowledge_sources.

Search strategies

search_knowledge supports two explicit strategies:

A specific search additionally returns the chunks immediately before and after the highest-ranked match, read from the same active document version. These neighbors restore context that chunking removed, such as the table header above a matched row or the sentence that introduces a matched list. Semantic matches keep their similarity score; a contextual neighbor instead carries a context_for_chunk marker naming the anchor chunk it supports, so the model never sees an artificial relevance score. Overview searches are not expanded.

The model can pass within with a source ID from list_knowledge_sources or a document ID from an earlier result. This narrows the same search machinery to one source or document. Within a document, results are returned in reading order rather than relevance order.

For “what does this source contain?” questions, semantic search is the wrong operation because there is no content query to embed. describe_source pages through document titles and includes a thin sample of excerpts. The model is instructed to finish the title listing before making a claim about the source’s coverage.

Turn lifecycle

1. Eneo checks that the assistant is in tool mode, has at least one knowledge source, and the effective model supports tool calling.
2. It mints one short-lived, assistant-scoped bearer token for the completion.
3. It creates an ephemeral in-memory MCPServer representation of the built-in knowledge endpoint and derives its tool definitions directly from the built-in FastMCP application.
4. The knowledge server is prepended to the external server list and enters the normal MCP proxy.
5. Eneo sends the prefixed tool definitions and a small source catalog to the model. No knowledge chunks are retrieved yet.
6. The model calls one or more knowledge tools. Eneo sends their results back into the same model turn and continues the tool loop.
7. Search results are MCP embedded resources. Eneo captures them through the generic MCP-reference pipeline so the final answer can cite them.

Bounds and context safety

The knowledge tools are deliberately paged and capped:

• a search call cannot return more than 20 semantically ranked chunks;
• specific search normally returns at most 6 semantic matches, plus up to two adjacent context chunks around the best match, bounding default output at 8 chunks;
• overview search normally returns at most 15 diversified chunks;
• full documents, source descriptions, and attached files use offsets for continuation;
• each MCP result is also subject to the proxy’s character limit;
• across a turn, tool results share an aggregate admission budget based on the same context-window share reserved for injected knowledge.

When the aggregate budget is exhausted, later results are replaced with an explicit instruction to stop calling tools and answer from the information already gathered. These layers prevent one call or a tool-happy model from silently overflowing the provider context window.

When tool mode is a good fit

• Questions are multi-part and benefit from several focused searches.
• The model should retry with different wording after a weak result.
• Users ask for broad corpus overviews as well as precise facts.
• The model sometimes needs a whole policy, procedure, or table after finding a relevant passage.
• Conserving context on turns unrelated to knowledge matters.

Tool mode depends more heavily on the model’s ability to choose tools and obey retrieval instructions. It can also add several model and HTTP round trips to a single user turn.

What “loopback MCP” means

Eneo registers built-in FastMCP applications under these backend routes:

/internal-mcp/knowledge/mcp
/internal-mcp/files/mcp
/internal-mcp/image_generation/mcp

The knowledge and files servers are attached ephemerally per completion, as described below. The image generation server is instead attached through an admin-registered provider row; Built-in Tool Servers contrasts the two patterns and states which features should be built-in at all.

During a completion, INTERNAL_MCP_BASE_URL is combined with one of those paths. The backend then connects through its ordinary Streamable HTTP MCP client, even though the destination is the same application deployment.

This apparently circular route provides a useful architectural property: after attachment, an internal capability and an external MCP server use one integration boundary. The completion adapter does not need separate execution logic for “RAG tools” and “MCP tools.” Prefixing, parallel calls, tool result conversion, UI metadata, reference capture, output limits, retries, and cleanup are shared.

Ephemeral client-side representation, permanent server-side route

The mounted HTTP applications live for the backend process lifetime. The MCPServer entity added to a particular completion does not:

• it gets a new ID for that completion;
• it is never written to the MCP server catalog;
• its tool definitions come from the built-in FastMCP application;
• it carries that completion’s short-lived bearer token;
• it is discarded when the request finishes.

The internal FastMCP applications use stateless HTTP. They do not assign an MCP protocol session ID, and any healthy backend worker can serve a loopback call.

Internal authentication and scope

The short-lived token authenticates the acting user and carries an assistant_id claim. A built-in tool does not accept an assistant ID as a model argument. Instead, it reads the fixed claim, authenticates the user, builds the normal dependency-injection graph for that user, and loads the assistant through the ordinary authorization services.

This design prevents a model from changing an argument to search another assistant. Knowledge queries remain limited to the sources attached to the token’s assistant. Missing and inaccessible documents return the same response so the tool does not become an existence oracle. Tenant checks also apply when the files tool resolves an attachment.

Attachment loopback server

The second built-in server, files, exposes files__read_file. It is attached when the effective model supports tools and the conversation contains files for which Eneo can provide authorised file references.

The model receives the filename, media type, size and a credential-free file_ref. Eneo replaces that handle with a signed URL immediately before calling the reader. The reader verifies the token, authorises the file, and loads already-extracted text from Eneo’s durable content path. It does not fetch the URL over HTTP.

This matters in two cases:

• when attachment text is also inline, the reader can page through text that did not fit comfortably in the active reasoning context;
• when inline_file_text is disabled, the reference and reader provide the model’s built-in path to the file text without eagerly placing it in the prompt.

Image files still reach vision-capable models as images. Audio references report that their transcription, when available, is already represented in the conversation.

URL-only attachments

A document is URL-only when the model receives its reference entry and nothing else: no extracted text and no rendered page images. The model decides whether to open it, and reads it through files__read_file or another tool that accepts the URL. This is what the editor calls opening a file on demand.

Three settings decide it, each for its own kind of file:

A file selected for on-demand access is still loaded directly when any of the following holds. For the assistant’s own files the editor shows the reason next to the file.

• The effective model does not support tool calling. A model that cannot call the reader would only see a link it cannot open.
• The file is not a text document. Images and audio are never URL-only.
• The file has no readable stored original, for example a row that predates durable originals. Upload it again to make it available on demand.
• The deployment has neither FILE_REFERENCE_BASE_URL nor a public origin, so Eneo cannot build a reference.

URL-only mode changes when the text enters the context, not how much of it a full read costs:

• files__read_file returns the extracted text in pages of at most 20,000 characters, or half of MCP_TOOL_OUTPUT_MAX_CHARS when that is smaller (16,384 characters with the default settings). Each page ends with the offset for the next one.
• Every page the model reads is a tool result in the conversation. A request such as “summarise this document” makes the model page through the whole file, so the full text ends up in context anyway. The saving comes from questions that need none or only part of the file, and from turns where the file is not opened at all.
• Pages that were read follow the replay rules in Conversation replay of tool use.
• The check that rejects attachments too large for the model’s context window counts only directly loaded files. A URL-only document of any size is accepted, and it is the model’s paging that has to fit.

Eneo has no built-in tool that summarises a document outside the context window. For files that are too large to read in full, connect a tool that processes the file itself and returns a bounded result, and let it take the same reference URL.

Internal and external MCP servers use one proxy

After availability and policy have been resolved, the proxy receives one ordered list:

[built-in knowledge, built-in files, allowed external server 1, ...]

Only servers that are actually needed are included. The knowledge server requires tool mode plus attached knowledge. The files server requires attachment references. External servers must survive the organization, space, assistant, governance, per-message, and enabled-state filters.

Comparison

This comparison covers the ephemeral knowledge/file servers and independently operated servers. The registered internal image provider has a different lifecycle but the same per-call approval rule; the bundled runtime is a separate service whose catalog follows Eneo’s code and whose calls follow the conversation’s approval setting. Tools and MCP Architecture compares all three tiers; Built-in Tool Servers describes the two loopback attachment patterns.

Naming and collision handling

Every exposed tool gets a model-facing name in this form:

sanitized-lowercase-server-name__sanitized-tool-name

Examples are knowledge__search_knowledge, files__read_file, and ticketing__create_issue. Prefixes allow different servers to expose an unprefixed tool with the same name without ambiguity.

Server and tool names are sanitized to the function-name character set. If two configured combinations collapse to the same prefixed name, the first registered tool wins and the later one is skipped with a warning. Internal servers are prepended, so the built-in tool wins an exact prefixed-name collision. The knowledge prompt also tells the model to prefer the built-in knowledge tools over similarly described tools when a question could be answered from the assistant’s attached knowledge.

This is precedence, not exclusivity. A single answer may legitimately combine:

• built-in knowledge for organizational policy;
• an external MCP tool for current operational state;
• another external tool for an action such as creating a ticket.

The model is instructed to attribute information from the appropriate tool and not represent an external result as if it came from attached knowledge.

Lazy connections and parallel execution

The proxy builds the initial model-facing registry from approved definitions without opening every server connection. It connects lazily when the model first calls a tool on a server and reuses that connection for later calls in the same completion. Before parallel tool calls run, required connections are opened on the proxy’s owner task; the independent calls can then execute in parallel safely.

When a progressive-discovery server advertises tools.listChanged, Eneo can re-list after activation calls. It still intersects the live list with the administrator-approved catalog. A remotely introduced or changed definition does not become callable merely because it appeared mid-conversation.

Two different kinds of approval

“Tool approval” can refer to two separate controls.

Catalog approval

Catalog approval is an administrator trust decision about what an external server is allowed to describe to the model. New tools and changed descriptions or input schemas are staged for review. Until approval:

• a new tool is hidden;
• an existing tool keeps its previous approved definition;
• a live server cannot replace an approved schema in the current request.

Internal tools do not enter this workflow because their definitions are built from the deployed Eneo code for each completion and are not remote catalog input.

Per-call user approval

Per-call approval happens after the model chooses an external tool. When the conversation requires approval, Eneo pauses execution and asks the user to approve or deny the proposed external calls. Built-in calls (knowledge, files and the built-in image provider) bypass this prompt: their scope is fixed by Eneo’s own code and the completion token, and the role, space and classification checks that attached them already decided that this user may use them. Bundled runtime calls are not built-in in this sense and follow the conversation setting.

An external tool can still be read-only, but Eneo does not infer safety from its name or description. It remains subject to the external approval policy.

How attachment references interoperate with external MCP

File references are useful beyond files__read_file. The model receives a credential-free file_ref (eneo-file:…) and passes it unchanged in an MCP tool’s URL input—for example, to a spreadsheet analysis service:

1. Eneo resolves the handle against the current request’s authorised file map and replaces it with a short-lived signed original-download URL.
2. The MCP server receives that URL as a normal argument. Its stored schema and implementation need no support for Eneo’s model-facing handles.
3. The server must reach FILE_REFERENCE_BASE_URL and download the original before the reference expires; the download still checks access.
4. The server processes the bytes and returns an MCP result. Accepted generated files receive their own handles for subsequent calls.

An unknown or unavailable handle fails before dispatch. Knowing a file ID is not authority to read it. Signed URLs remain the provider-facing transport; they are not the file identifiers exposed to the model.

The built-in files server remains the authorized raw-text fallback. If another tool fails while its arguments contain an Eneo reference URL, the proxy appends a hint: when the files server is attached, to retry the same file reference with files__read_file instead of repeatedly calling the failed service; otherwise, that the reference is valid, so the model reports that the tool cannot reach the file rather than asking the user to upload it again.

FILE_REFERENCE_BASE_URL and INTERNAL_MCP_BASE_URL solve different routing problems. The former must be reachable by URL-consuming tools that need file bytes. The latter must be reachable by Eneo’s own backend so it can call its built-in MCP routes.

Conversation replay of tool use

Eneo opens a fresh MCP connection per completion and does not persist MCP protocol sessions. Cross-turn continuity lives in the conversation’s tool trace instead: tool metadata records the exact prefixed name, arguments, result status, and result text needed to replay prior tool use to the model. MCP resource blocks are captured generically, regardless of whether the provider was internal or external. A server that holds state across turns returns an explicit handle in its tool results; because prior results are replayed, the model can pass that handle to later calls.

Failure and degradation behavior

Eneo contains failures at the smallest useful boundary where possible.

Configuration and deployment

The most relevant backend settings are:

For a normal single-process development backend, the default loopback URL works without configuration. In production, it must point to an address reachable from the backend container or process. If a reverse proxy intentionally blocks /internal-mcp, keep the loopback base on the backend’s private service address rather than the public origin.

The loopback endpoints require their scoped bearer tokens, but operators should still avoid exposing internal routes unnecessarily. Network isolation is an additional boundary, not a replacement for application authentication.

Both retrieval paths run the same pgvector query: chunks in scope are ordered by cosine distance to the query embedding. The embedding column has no approximate-nearest-neighbour index (it is declared without a fixed dimension, so one cannot be created), and the repository disables sequential scans for the query to keep PostgreSQL on the scope indexes. Retrieval latency therefore grows with the size of the searched corpus rather than staying flat.

Observability

The backend emits structured log messages that distinguish retrieval and proxy decisions:

• [RAG] records the stored knowledge mode, attached source counts, model tool capability, chosen runtime path, search mode, scope, and result counts;
• [FILES] records files-server attachment and paged reads without logging file contents;
• [MCP] and [MCPProxy] record proxy creation, registry size, connections, catalog refresh, collisions, tool timing, and failure containment.

Useful diagnosis order:

1. Confirm the assistant has knowledge and the expected stored mode.
2. Confirm the effective model advertises tool calling.
3. Look for the [RAG] ... -> knowledge tool attached or legacy inject retrieval decision.
4. If tool mode was selected, confirm INTERNAL_MCP_BASE_URL is reachable from the backend process.
5. Inspect proxy registry and connection logs for knowledge, files, and any external server involved.
6. For missing external tools, check organization, space, assistant, per-message, catalog approval, live identity catalog, and security-classification filters in that order.

Choosing a mode

A practical default for a capable tool-calling model is tool, especially for large or varied knowledge bases. Use inject when compatibility and a simple, predictable path are more important than iterative retrieval. Because fallback is automatic, selecting tool does not make the assistant unusable with a non-tool model; it changes the preferred path when the model can support it.

Worked examples

Knowledge only

The user asks, “What is our retention period for case notes?” The assistant has the records policy attached and is in tool mode.

1. The model calls knowledge__search_knowledge with a focused query in the source language.
2. The search returns a policy passage as an embedded MCP resource.
3. If the passage is sufficient, the model answers with its reference. If it names an exception elsewhere in the policy, the model calls knowledge__read_source for more context.

No external server is needed, even if one happens to expose a generic document search tool.

Knowledge plus live external data

The user asks, “What does our incident procedure require, and are there open incidents right now?”

1. The model searches built-in knowledge for the procedure.
2. It calls the external incident system for current status.
3. Eneo can execute independent calls in parallel after their connections are ready.
4. The final answer attributes procedure claims to knowledge sources and live status to the incident tool.

Attachment plus specialized external processing

The user attaches a spreadsheet and asks for an analysis. Eneo provides a credential-free file reference and the built-in files server.

1. The model may pass the reference to an approved spreadsheet-analysis MCP tool.
2. If that tool cannot retrieve or process the file, the proxy points the model to files__read_file as the raw-text fallback.
3. The model answers from the successful tool result and the persisted tool trace shows which path it used.

Implementation map

For contributors, the main boundaries are:

The central invariant is that internal and external MCP capabilities converge at the proxy only after each kind has applied its own availability, authorization, and trust decisions. Sharing execution plumbing does not erase their different security and lifecycle boundaries.