MCP server
The API server includes a Model Context Protocol (MCP) server at the path /mcp. MCP is an open protocol through which AI assistants and other MCP clients discover the tools, prompts and resources that a server offers and use them. This page describes the role of the MCP server, the transport, host names, protocol revisions and authentication, the tools, prompts and resources, the API keys for AI assistants and the current limits. Integrators need this page to connect an AI assistant to Foundation4, and administrators need this page to issue API keys for MCP clients.
Role of the MCP server
The MCP server gives an AI assistant the operations of the REST API that a conversation needs: finding pipelines, searching, reading documents, adding, expiring and deleting documents, and running agents. The language model of the assistant decides which tool to call, with which arguments, from the tool descriptions and the server instructions that the MCP server sends.
An AI assistant answers a question from Foundation4 content in one of two ways:
- Assistant model. The assistant retrieves fragments with
search_knowledge, or gets an agent's messages with the fragments inserted as an MCP prompt, and the assistant's own language model writes the answer. No Foundation4 LLM takes part. In this mode, the MCP server provides the retrieval step of retrieval-augmented generation (RAG) for an AI assistant outside Foundation4. - Foundation4 LLM. The assistant calls
run_agent, and a Foundation4 agent retrieves the fragments and asks a registered LLM, as a REST execution does. The assistant receives the answer and, as sources to cite, the fragments that the LLM received.
The MCP server runs inside the API server process. Each tool calls the same operation as a REST endpoint, reads the same data and requires the same permissions. MCP tools lists the arguments, the output and the errors of each tool, and Connect an AI assistant over MCP describes the setup.
Transport
The MCP server uses the streamable HTTP transport of MCP, without sessions. A client sends each JSON-RPC request or notification in a POST request to one URL, $FOUNDATION4_URL/mcp, without a trailing slash. The path /mcp/ returns HTTP 404. Every other method, including GET and DELETE, returns HTTP 405 with the header Allow: POST: the server sends no messages of its own, so a client opens no event stream.
Every POST carries the header Content-Type: application/json and an Accept header that lists both application/json and text/event-stream. A request without these headers returns HTTP 406 or HTTP 415 with a plain-text body.
The server answers each JSON-RPC request with the JSON-RPC response in a body with the content type application/json. A notification receives HTTP 202 with an empty body. Responses carry the x-request-id header described in API conventions. A request body larger than 4 MiB returns HTTP 413.
Host names
By default, the MCP server accepts a request for any host name in the Host header. An MCP client therefore reaches the MCP server at the same base URL as the REST API: the host name of the ingress or HTTPRoute, the Service name foundation4ai-api-server inside the cluster, or http://localhost:8080 through a port forward. API and dashboard access describes the three access paths.
The setting mcp.allowed_hosts of the API server configuration restricts the accepted host names. The setting takes a list of entries: a host name, such as foundation4.example.com, accepts the name with any port, and a host name with a port, such as foundation4.example.com:8443, accepts that port only. localhost, 127.0.0.1 and ::1 remain accepted with any list, so that a port forward keeps working. The default ["*"] accepts every host name. A request for a host name outside the list returns HTTP 403 with the plain-text body Forbidden: Host header is not allowed. The chart sets no value for mcp.allowed_hosts, so a deployment that restricts the host names adds the setting in a configs entry, as described in Configuration reference.
The host check protects an MCP server that runs on a workstation against Domain Name System (DNS) rebinding, an attack in which a web page reaches a local server through the visitor's browser. The Foundation4 MCP server authenticates every request with API key headers, never with cookies, so a browser holds no credential that such a page could reuse.
Protocol revisions
The MCP server supports the MCP protocol revisions 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 and 2026-07-28. The initialize request names the revision that the client uses. The server answers with the same revision when the revision is one of the first four, and with 2025-11-25 otherwise, because the revision 2026-07-28 has no initialize request.
The server keeps no session for any revision:
- No session identifier. The response to
initializecarries noMcp-Session-Idheader. A client may sendnotifications/initializedafterinitialize, as the protocol requires, and receives HTTP 202, but no request depends on an earlier one. - Revision header. A request other than
initializenames the revision in theMCP-Protocol-Versionheader. A request without the header counts as revision2025-03-26, and a header that names an unsupported revision returns HTTP 400. - Replicas. Any API server replica answers any request, so a replica restart or a long idle period interrupts no client, and a deployment with several API server replicas needs no session affinity at the ingress for MCP clients.
For the revision 2026-07-28, each request also carries the per-request protocol metadata and headers that the revision defines, including the client capabilities in _meta. MCP tools shows such a request.
Authentication
The MCP server uses the API keys of the REST API. Every HTTP request to /mcp, including initialize and notifications, carries the x-api-key and x-api-key-secret headers described in Authenticate. A request without valid headers returns HTTP 401 with the JSON error body of the REST API, before the MCP server reads the request. Errors lists the authentication messages.
Each tool call runs with the permissions of the API key in the headers of the HTTP request that carries the call, so two requests of the same client can carry different keys.
Tools
The MCP server offers 18 tools in five groups. Each tool corresponds to a REST operation and requires the permissions of that operation, described in Access control.
| Group | Tools | REST operations |
|---|---|---|
| Pipelines | get_pipelines, get_pipeline, get_pipeline_classifications | GET /pipelines, GET /pipelines/{id}, GET /pipelines/{id}/classifications |
| Search | search_knowledge | POST /pipelines/{id}/search |
| Documents | list_paths, list_documents, get_document, get_document_fragments, get_document_versions, add_document, expire_document, delete_document | The path list, the document list, document reads, fragments, versions, document creation, expiry and deletion |
| Taxonomies | list_taxonomies, get_taxonomy_entries | GET /taxonomies, GET /taxonomies/{id}/entries |
| Agents | list_agents, list_llms, agent_search, run_agent | GET /agents, GET /llms, POST /agents/{id}/search, POST /agents/{id}/execute |
search_knowledge runs every search type of Search and retrieval: similarity, MMR, full-text (text), hybrid and history (latest) search, on the default indexes or on named search indexes, with a metadata filter and a path pattern. The arguments are flat, such as search_type, k and filters, rather than a params object. get_pipelines and get_pipeline list the search indexes of each pipeline, and get_pipeline returns the metadata schema from which the assistant builds filters.
Each tool carries annotations that tell the client whether the tool changes data. add_document, expire_document, delete_document and run_agent are not read-only, and expire_document and delete_document are marked destructive, so many MCP clients ask the user to confirm those calls. run_agent changes no data, but each call sends the retrieved fragments to the agent's LLM, so the tool is marked neither read-only nor idempotent, and is marked open-world. The annotations are hints for the client: the permissions of the key decide which calls succeed. Each result carries the tool output twice, as structured content and as the same JSON in a text block for MCP clients that read text only.
Prompts and resources
The MCP server also offers prompts and resources:
- Prompts. Each agent that the key can read is an MCP prompt with the name of the agent. The prompt takes the pipeline, the classifications, an optional path pattern and the agent's input variables. Getting the prompt runs the agent's retrieval placeholders and returns the agent's messages with the fragments inserted, for the assistant's own language model. An MCP client usually offers prompts to the user as commands, so the user selects the agent rather than the language model.
- Resources. The text of each document is a resource with the URI
f4ai://pipelines/{pipeline_id}/documents/{document_id}, which the document tools return inresource_uri. Reading the resource returns the text of the current version, assembled from the document's fragments. The server lists no documents as resources, because a pipeline can hold millions, and publishes the URI template instead.
MCP tools describes the arguments and results of both.
API keys for AI assistants
The language model of the assistant chooses the arguments of every tool call, including the classifications of a search and the documents to delete. The permissions and the classification allow-list of the key therefore set what the assistant can reach and change, whatever the user asks the assistant. A key for an AI assistant follows the principle of least privilege:
| Use | Permissions |
|---|---|
| Search and read one pipeline | 5 (read and execute) on the pipeline, with an allow-list of the classifications that every user of the assistant may read |
| Add documents as well | Also 1 (execute) on the pipeline's default text splitter, and each classification of the added documents in the allow-list |
| Expire and delete documents as well | 7 (read, write and execute) on the pipeline |
| Use agents | 5 on each agent, 5 on each LLM that run_agent names, and the agents' pipelines as above |
| Use taxonomies | 4 (read) on each taxonomy |
A key with 5 on a pipeline and no permission on the text splitter can search but cannot add documents: add_document returns an error. A key without write permission cannot expire or delete documents. A path pattern selects documents and grants no access, as described in Document paths, so content that some users of an assistant must not see is separated by classification or by pipeline.
Current limits
The following limits apply to the MCP server:
- Header authentication. The MCP server does not implement the OAuth-based authorization of the MCP specification and publishes no authorization metadata. An MCP client connects only when the client can send custom HTTP headers with every request.
- Object management. The tools change documents only. Pipelines, search indexes, agents, LLMs, taxonomies and API keys are created and changed through the REST API.
- Agent answers.
run_agentreturns the complete answer after the LLM finishes, without streaming. - Prompt arguments. MCP prompt arguments are strings, so an agent prompt takes the classifications as one comma-separated string and accepts no metadata filter.
- Listing pages. The list tools for pipelines, taxonomies, agents and LLMs return no page information, and only
get_pipelinesreturns a total count, intotal. A client reads further pages with theoffsetargument until a call returns fewer objects thanlimit.
Example exchange
The following exchange initializes the connection and runs a similarity search. The commands use the shell variables described in Authenticate, and $PIPELINE_ID holds the identifier of the support-kb pipeline from First search.
The initialize request names the protocol revision and the client:
curl -i -X POST "$FOUNDATION4_URL/mcp" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1.0"}}}'
The response has status 200, the content type application/json and no session header. The body holds the result, shown here formatted and without the instructions field, which MCP tools quotes in full:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-11-25",
"capabilities": {"prompts": {}, "resources": {}, "tools": {}},
"serverInfo": {"name": "foundation4ai", "title": "Foundation4.ai", "version": "1.1.0"}
}
}
The result names the negotiated revision, the three capabilities and the server information, whose version is the Foundation4 release. The server keeps no state from the initialize request, so the next request carries no session header. The tools/call request runs search_knowledge with the default search type, similarity:
curl -X POST "$FOUNDATION4_URL/mcp" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-11-25" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "search_knowledge",
"arguments": {
"pipeline_id": "'"$PIPELINE_ID"'",
"query": "How do customers get their money back?",
"classifications": ["internal"],
"k": 1
}
}
}'
The response has status 200 and the content type application/json. The result object of the response, formatted, shows the three parts of a tool result:
{
"content": [
{
"type": "text",
"text": "{\"results\":[{\"classification\":\"internal\",\"document_id\":\"01a0ed0d-df3f-7f80-9a1b-2c3d4e5f6a7b\",\"expired_at\":null,\"id\":\"01a0ed0d-e007-7c3d-8e4f-6a7b8c9d0e1f\",\"metadata\":{\"product\":\"billing\"},\"order_id\":0,\"page_content\":\"Refunds for annual plans are prorated. Support agents must record the refund reason in the ticket before approving a refund.\",\"path\":null,\"score\":0.6444976753595035,\"version\":1790683504447128}]}"
}
],
"structuredContent": {
"results": [
{
"classification": "internal",
"document_id": "01a0ed0d-df3f-7f80-9a1b-2c3d4e5f6a7b",
"expired_at": null,
"id": "01a0ed0d-e007-7c3d-8e4f-6a7b8c9d0e1f",
"metadata": {"product": "billing"},
"order_id": 0,
"page_content": "Refunds for annual plans are prorated. Support agents must record the refund reason in the ticket before approving a refund.",
"path": null,
"score": 0.6444976753595035,
"version": 1790683504447128
}
]
},
"isError": false
}
The fragment fields are the fields of a REST search result, in alphabetical order. The score is the distance that REST search returns for the same query, shown at full precision; Search requests shows the same fragment rounded to 0.6445. A failed tool call returns a JSON-RPC error object with a code and a message instead of result, as described in MCP tools.