MCP tools
This page lists what the Foundation4 Model Context Protocol (MCP) server offers to an MCP client: the server information of the initialize response, the 18 tools with their arguments, outputs, annotations, permissions and errors, the prompts built from agents, the document resources and the HTTP errors of the /mcp endpoint. Integrators use this page to configure an MCP client and to interpret tool results. MCP server describes the transport, protocol revisions, authentication and the role of each group of tools.
Server information
The initialize response returns the following server information:
| Field | Value | Description |
|---|---|---|
protocolVersion | The revision named in the request, or 2025-11-25 | The server supports the revisions 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 and 2026-07-28. A request for any other revision receives 2025-11-25. |
capabilities | {"prompts": {}, "resources": {}, "tools": {}} | Tools, prompts and resources. The server sends no list change notifications and declares no completions or logging. |
serverInfo.name | foundation4ai | A fixed name. The branding name configuration does not change the value. |
serverInfo.title | Foundation4.ai | A fixed display name. The branding name configuration does not change the value. |
serverInfo.version | The Foundation4 release, such as 1.1.0 | An image built with a build identifier reports the release followed by + and the identifier |
instructions | The text below | A fixed text for the language model of the client. The branding name configuration does not change the text. |
The instructions field holds the following text, which tells the client's language model how the tools fit together:
Foundation4.ai is a knowledge base: pipelines hold documents, split into fragments and indexed for search.
1. Find a pipeline with get_pipelines, and its classifications with get_pipeline_classifications: every search needs classifications, and only returns documents of the classifications you may read.
2. Search with search_knowledge: `similarity` (the default) for meaning, `text` for exact keywords, `hybrid` to combine both. Narrow results with metadata `filters` built from the pipeline schema (see get_pipeline).
3. Read around a result with get_document_fragments, or attach the whole document through its resource URI (`f4ai://pipelines/{pipeline_id}/documents/{document_id}`).
4. Agents (list_agents) are prompt templates that retrieve from a pipeline: run_agent asks a Foundation4.ai LLM, or use the agent as an MCP prompt to answer with your own model.
Documents added with add_document are processed in the background and can be searched once their status is `success`.
The server also answers ping with an empty result. completion/complete, logging/setLevel and resources/subscribe return the JSON-RPC error -32601, because the server declares no completions, logging or subscriptions.
Tool list
tools/list returns the 18 tools in alphabetical order, in one page without a nextCursor. Each tool definition contains name, description, inputSchema, outputSchema and annotations, and no title. The schemas follow JSON Schema draft 2020-12 and describe the same arguments and output fields as the tables on this page.
| Tool | Description sent to the client |
|---|---|
add_document | Add a document to a pipeline. It is split and indexed in the background: it is `pending` until then, and can be searched once `success` (see get_document). |
agent_search | Run an agent's retrieval only: the fragments each of its retrieval steps finds in a pipeline, without calling an LLM |
delete_document | Delete a document and all its versions. This cannot be undone: prefer expire_document to keep its history. |
expire_document | Expire a document: it is no longer returned by searches, but its versions are kept and can still be read |
get_document | Get a document of a pipeline: its current version, classification, metadata and processing status |
get_document_fragments | Read a document's fragments in order, e.g. to see the context around a search result |
get_document_versions | List the versions of a document, newest first |
get_pipeline | Get a pipeline: its search indexes and the JSON schema of its documents' metadata, which metadata filters use |
get_pipeline_classifications | List the document classifications of a pipeline you can read, and which classifications inherit from which |
get_pipelines | List the pipelines (knowledge bases) you can access, with their search indexes |
get_taxonomy_entries | List the entries of a taxonomy: parent terms and the child terms they relate to |
list_agents | List the agents: prompt templates that retrieve from a pipeline and ask an LLM. Each agent is also available as an MCP prompt of the same name. |
list_documents | List the documents of a pipeline, optionally filtered by external identifier, status or metadata |
list_llms | List the LLMs agents can run with (see run_agent) |
list_paths | List the paths (locations) of a pipeline's documents, with how many documents are at each one, in order; use them as the `path` of search_knowledge, agent_search, run_agent and list_documents |
list_taxonomies | List the taxonomies: vocabularies that map terms to related terms, e.g. to expand metadata filters |
run_agent | Run an agent: retrieve from a pipeline, render its prompt and get the LLM's answer, with the fragments the LLM was given as sources to cite |
search_knowledge | Search a pipeline for the fragments of documents that answer a query. Returns ranked fragments with their text, score, document and classification; read a whole document with get_document_fragments or its resource URI. |
The annotations describe the effect of each tool. MCP clients treat annotations as hints, for example to decide whether a call needs the user's confirmation.
| Tool | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |
|---|---|---|---|---|
add_document | false | false | false | false |
delete_document, expire_document | false | true | true | false |
run_agent | false | false | false | true |
| Every other tool | true | false | true | false |
run_agent carries openWorldHint because the tool sends the prompt, with the retrieved fragments, to a model server outside the API server. run_agent changes no data but carries neither readOnlyHint nor idempotentHint, because each call sends content to the model server, so MCP clients that confirm such calls ask the user before running the tool, as described in MCP server.
Tool results
A successful tool call returns a result object with three fields:
| Field | Type | Description |
|---|---|---|
content | Array | One text block, {"type": "text", "text": "<JSON>"}, whose text is the tool output serialized as a JSON string |
structuredContent | Object | The tool output as a JSON object, described by the outputSchema of the tool |
isError | Boolean | false |
The keys of every object in the tool output appear in alphabetical order, in both content and structuredContent. The examples on this page show structuredContent. The MCP server page shows a complete response.
With the protocol revision 2026-07-28, which has no initialize request, each request carries the revision in the MCP-Protocol-Version header and carries the revision and the client capabilities in _meta. The following tool call uses the revision:
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: 2026-07-28" \
-H "Mcp-Method: tools/call" \
-H "Mcp-Name: get_pipelines" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_pipelines",
"arguments": {"query": "support"},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'
The response has the content type application/json. The result object carries the field "resultType": "complete" before content, structuredContent and isError. A request whose _meta lacks io.modelcontextprotocol/clientCapabilities receives HTTP status 400 and the JSON-RPC error -32602 request _meta is missing or has malformed required fields: io.modelcontextprotocol/clientCapabilities.
Output objects
Several tools return the same objects. The tables in this section describe each object once.
Pipeline
get_pipelines returns a list of pipeline objects, and get_pipeline returns one pipeline object with the additional field schema.
| Field | Type | Description |
|---|---|---|
pipeline_id | String | The pipeline identifier |
name | String | The pipeline name |
description | String or null | The pipeline description |
default_vector_index_id | String or null | The identifier of the default vector index, which the REST API returns as default_vector_embedding_index_id |
default_text_search_index_id | String or null | The identifier of the default text index, a full-text or a BM25 index |
search_indexers | Array | The search indexes of the pipeline, ordered by identifier, described in Search index |
default_text_splitter_id | String | The identifier of the pipeline's default text splitter |
schema | Object | get_pipeline only: the JSON Schema of the documents' metadata, which metadata filters and add_document follow |
Search index
| Field | Type | Description |
|---|---|---|
id | String | The identifier of the search index, the value that search_index_ids of search_knowledge takes |
kind | String | vchord for a VectorChord index and pgvector for a pgvector index, the vector indexes that similarity and MMR search read; fts for a full-text index and bm25 for a BM25 index, which full-text search reads. Hybrid search combines any kinds. |
embedding_model | String or null | The name of the embedding model of a vector index, null for a text index |
status | String | ready when the index can be searched, building while the workers fill the index, failed when the fill failed |
Search indexes describes the index kinds and statuses.
Fragment
search_knowledge, get_document_fragments and agent_search return fragments with the following fields, and run_agent returns the same fragments without page_content. The fields are those of a REST search result, without embedding.
| Field | Type | Description |
|---|---|---|
id | String | The fragment identifier |
classification | String | The classification of the fragment's document |
metadata | Object | The metadata of the fragment's document |
path | String or null | The path of the fragment's document version, or null for a document without a path |
document_id | String | The identifier of the document |
page_content | String | The decrypted text of the fragment. The field is absent when the text is empty. |
version | Integer | The document version, in microseconds since the Unix epoch |
expired_at | String or null | The time at which the document version expired, null for a current version |
score | Number or null | The score of a search result: the distance for similarity and MMR search, the rank or BM25 score for full-text search, the fused score for hybrid search. null for history search and for get_document_fragments. |
order_id | Integer | The position of the fragment within the document version, starting at 0 |
Document
list_documents, get_document, get_document_versions and add_document return documents with the following fields:
| Field | Type | Description |
|---|---|---|
document_id | String | The document identifier, which the REST API returns as id |
version | Integer | The document version, in microseconds since the Unix epoch |
pipeline_id | String | The identifier of the pipeline |
classification | String | The classification of the document |
external_identifier | String or null | The client application's identifier for the document |
metadata | Object | The metadata of the document |
path | String or null | The path of the document version, or null |
status | String | pending, success, failed or canceled, as described in Ingest documents reliably |
message | String or null | The reason for a failed status |
created_at | String | The creation time of the version, in RFC 3339 format |
expired_at | String or null | The time at which the version expired |
resource_uri | String | The URI of the document's text as an MCP resource, described in Resources |
Pages
Tools that list objects return a results array. Two forms of paging apply:
- Cursor pages.
list_paths,list_documentsandget_document_fragmentsreturnnext_cursorbesideresultswhen a further page may exist. A call withcursorset to that value returns the next page. The field is absent on the last page. - Offset pages.
get_pipelines,list_taxonomies,get_taxonomy_entries,list_agentsandlist_llmstakelimitandoffsetand return no page information.get_pipelinesalso returnstotal, the number of matching pipelines across all pages. A client reads the next page withoffsetincreased bylimit, until a call returns fewer objects thanlimit. Alimitoutside 1 to 1,000 returns -32602Pagination error, withdataset to{"error": "limit must be between 1 and 1000, got 0"}for alimitof 0.
The query argument of get_pipelines, list_taxonomies, list_agents and list_llms returns only the objects whose name contains the text, case-sensitive. The characters % and _ in the text match themselves.
Tool errors
A failed tool call returns an error in one of two forms. When the arguments do not match the types of the input schema, the response is a result with isError set to true and one text block:
| Cause | Text |
|---|---|
| A required argument is missing | failed to deserialize parameters: missing field `pipeline_id` |
| An argument has the wrong type | failed to deserialize parameters: invalid type: string "5", expected u16 |
search_type has an undefined value | failed to deserialize parameters: unknown variant `history`, expected one of `similarity`, `mmr`, `text`, `hybrid`, `latest` |
Arguments that the input schema does not define are ignored without an error. The arguments type, params and embedding_model_id of the search tool of earlier releases are therefore ignored: such a call runs a similarity search with the default parameters on the default vector index.
When the tool runs and the operation fails, the response is a JSON-RPC error object with code, message and, for some errors, data. The tools call the operations of the REST API, and each REST error maps to one code:
| Code | Meaning | Errors |
|---|---|---|
| -32602 | Invalid parameters | An identifier that is not a universally unique identifier (UUID), such as `pipeline_id` is not a valid identifier: invalid length: found 3; an invalid metadata filter (`filters` is not a valid filter: <reason>); an invalid path pattern (`path` is not a valid path: <reason>); tool not found; and every REST error with HTTP status 400, 403, 409, 422 or 501, with the REST message and the REST details in data |
| -32002 | Resource not found | Pipeline not found and Document not found, with data set to {"id": "<identifier>"}, and every REST error with HTTP status 404 |
| -32603 | Internal error | Server-side failures, with the REST message, such as Internal server error or Provider unavailable, and no data, and a failed LLM call of run_agent, with the message described in run_agent. The API server log records the cause. |
A REST error with HTTP status 403 includes a search that names a classification outside the classification allow-list of the key, as described in Access control. A filter on a field that the pipeline schema does not declare returns -32602 with the message Schema error.
The following response reports a pipeline that does not exist or that the key cannot use:
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32002,
"message": "Pipeline not found",
"data": {"id": "7d3e9a41-2b6c-4f8d-9e1a-5c0b3f6a8d27"}
}
}
HTTP errors
The /mcp endpoint returns the following HTTP errors before a tool runs. Status 401, 404 and 405 return the JSON error body of the REST API, and the JSON-RPC errors return a JSON-RPC error object. The other bodies are plain text.
| Status | Body | Cause |
|---|---|---|
| 400 | Bad Request: Unsupported MCP-Protocol-Version: <value> | The MCP-Protocol-Version header names a revision that the server does not support |
| 400 | JSON-RPC error -32600 Invalid Request: MCP-Protocol-Version header (<header>) does not match initialize params.protocolVersion (<version>) | An initialize request whose MCP-Protocol-Version header names another revision than protocolVersion in the body |
| 400 | JSON-RPC error -32600 stateless server does not accept JSON-RPC responses | The body is a JSON-RPC response or error. The server sends no requests to clients, so no response is expected. |
| 400 | JSON-RPC error -32602 request _meta is missing or has malformed required fields: <field> | A request with the revision 2026-07-28 whose _meta lacks a required field, such as io.modelcontextprotocol/clientCapabilities |
| 401 | JSON error body, such as Unauthorized: No API Key specified. | The API key headers are missing or invalid, as described in Errors |
| 403 | Forbidden: Host header is not allowed | The deployment restricts the host names of the MCP server, and the Host header names another host, as described in MCP server |
| 404 | JSON error body Not found | A path under /mcp, such as /mcp/ |
| 405 | JSON error body Method not allowed | A method other than POST, such as GET or DELETE. The Allow header names POST. |
| 406 | Not Acceptable: Client must accept both application/json and text/event-stream | The Accept header of a POST request does not list both types |
| 413 | Payload Too Large: request body exceeds 4194304 bytes | The body is larger than 4 MiB |
| 415 | Unsupported Media Type: Content-Type must be application/json | The Content-Type header is not application/json |
| 415 | fail to deserialize request body <reason> | The body is not a JSON-RPC message |
Pipeline tools
get_pipelines
get_pipelines lists the pipelines that the API key can read, with offset pages. The tool corresponds to GET /pipelines with the name$contains filter.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
limit | Integer, 1 to 1,000 | No | 10 | The maximum number of pipelines to return |
offset | Integer, 0 or greater | No | 0 | The number of pipelines to skip |
query | String | No | None | Returns only the pipelines whose name contains the text, as described in Pages |
The call can omit arguments entirely. The output object has two fields: results, an array of pipeline objects without schema, and total, the number of pipelines that the key can read and that match query, across all pages.
- Permissions. Read on each pipeline returned. A key without read permission on any pipeline receives an empty
resultsarray. - Errors. Argument type errors, such as a negative
limit, return a result withisErrorset totrue.
The following call reads the pipelines whose name contains support:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {"name": "get_pipelines", "arguments": {"query": "support"}}
}
The structuredContent of the result for the support-kb pipeline of First search, which has a vector index and a full-text index:
{
"results": [
{
"default_text_search_index_id": "8e3b6f1d-2c4a-4d7e-9b05-6a1f2e3d4c5b",
"default_text_splitter_id": "019252e9-b4a0-7713-9a69-d701b4f4a2d1",
"default_vector_index_id": "5d1e8c2a-3f4b-4a6c-9e7d-1b2c3d4e5f60",
"description": "Support knowledge base",
"name": "support-kb",
"pipeline_id": "c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06",
"search_indexers": [
{
"embedding_model": "all-MiniLM-L6-v2",
"id": "5d1e8c2a-3f4b-4a6c-9e7d-1b2c3d4e5f60",
"kind": "vchord",
"status": "ready"
},
{
"embedding_model": null,
"id": "8e3b6f1d-2c4a-4d7e-9b05-6a1f2e3d4c5b",
"kind": "fts",
"status": "ready"
}
]
}
],
"total": 1
}
get_pipeline
get_pipeline returns one pipeline object with the metadata schema of the pipeline. A client uses the schema to build metadata filters for search_knowledge and metadata for add_document. The tool corresponds to GET /pipelines/{id}.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
For the support-kb pipeline, the result holds the fields of the get_pipelines example and "schema": {"properties": {"product": {"type": "string"}}, "type": "object"}.
- Permissions. Read on the pipeline.
- Errors. A pipeline that does not exist, or on which the key lacks read permission, returns error -32002
Pipeline not found.
get_pipeline_classifications
get_pipeline_classifications returns the classifications of one pipeline that the key can use, and the inheritance relationships between the classifications. The tool corresponds to GET /pipelines/{id}/classifications and returns the same object.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
| Field | Type | Description |
|---|---|---|
classifications | Array of strings | The classifications of the pipeline that the key's classification allow-list names, or every classification with the allow-list * |
hierarchy | Array of pairs of strings | The inheritance relationships. Each pair names a classification and a classification that the first classification inherits. |
The structuredContent of the result for the support-kb pipeline, which defines public and internal, where internal inherits public, with a key whose allow-list is *:
{
"classifications": ["internal", "public"],
"hierarchy": [["internal", "public"]]
}
Classifications describes inheritance.
- Permissions. Read on the pipeline.
- Errors. A pipeline that does not exist, or on which the key lacks read permission, returns error -32002
Pipeline not found.
Search tool
search_knowledge
search_knowledge runs one search on one pipeline and returns the ranked fragments. The tool corresponds to POST /pipelines/{id}/search, described in Search requests, with flat arguments in place of the params object.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
query | String | Yes | None | The search text. latest ignores the text. |
classifications | Array of strings | Yes | None | The classifications that the reader holds. Each named classification and every classification that the named classification inherits are searched. An empty array returns no fragments. |
exact_classifications | Boolean | No | false | Searches only the named classifications, without inheritance, and returns an error when the pipeline does not define a named classification |
search_type | String | No | similarity | The search type, from the table below |
search_index_ids | Array of strings | No | The default indexes | The search indexes to read: one vector index for similarity and mmr, one text index for text, any number and mix of indexes for hybrid. latest reads no index. |
k | Integer, 1 to 65535 | No | 5 | The number of fragments to return |
threshold | Number | No | None | For similarity and mmr, the maximum distance from the query. For text, the minimum score. hybrid and latest ignore the argument. |
fetch_k | Integer, k to 65535 | No | 10, or k when k is greater | mmr only: the number of candidates from which MMR search selects k fragments |
lambda_mult | Number, 0 to 1 | No | 0.5 | mmr only: the balance between relevance (1) and diversity (0) |
path | String | No | Documents without a path | A path pattern, such as kb.billing.>, described in Document paths. Without the argument, the search covers only the documents without a path. |
filters | Object | No | No filter | A metadata filter in the language of Filter operators |
The search types of the tool correspond to the search types of the REST API:
search_type | REST type | Search |
|---|---|---|
similarity | similarity | The k fragments closest in meaning to the query |
mmr | mmr | Maximal marginal relevance (MMR) search: k fragments selected from the fetch_k closest fragments for relevance and diversity |
text | search | Full-text search on a full-text index or a BM25 index |
hybrid | hybrid | The result lists of several search indexes, fused by reciprocal rank fusion |
latest | history | The k most recent fragments of the classifications that pass the filter, newest document version first |
The output object has one field, results, an array of fragments in the order of REST search: by ascending distance for similarity and MMR search, and by descending score for full-text and hybrid search. The tool differs from the REST operation in three points:
- Classifications. The tool takes an array of classification names. The REST operation also accepts a string and an object form.
- Distance strategy. Similarity and MMR search use the default distance strategy of the vector index. The tool has no
distance_strategyargument. - MMR candidates. Without
fetch_k, MMR search draws on at leastkcandidates, where the REST operation uses 10.
The following call runs an MMR search for 5 fragments from 20 candidates:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "search_knowledge",
"arguments": {
"pipeline_id": "c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06",
"query": "How do I rotate the database credentials?",
"classifications": ["internal"],
"search_type": "mmr",
"k": 5,
"fetch_k": 20
}
}
}
The structuredContent of the result for the support-kb pipeline of First search. The pipeline holds no document about database credentials, so the search returns the three fragments of the pipeline by ascending distance. A threshold drops fragments beyond a given distance.
{
"results": [
{
"classification": "public",
"document_id": "01a0ed0d-cf82-7c3d-8e4f-5a6b7c8d9e0f",
"expired_at": null,
"id": "01a0ed0d-d291-7c5d-8e4f-3a2b1c0d9e8f",
"metadata": {"product": "accounts"},
"order_id": 0,
"page_content": "To reset a password, open Settings, choose Security and select Reset password. A reset link is sent to the registered email address and expires after 30 minutes.",
"path": null,
"score": 0.6850275409090324,
"version": 1790683500418273
},
{
"classification": "internal",
"document_id": "01a0ed0d-d75f-7d5e-8f60-718293a4b5c6",
"expired_at": null,
"id": "01a0ed0d-d814-7d6c-8b5a-4c3d2e1f0a9b",
"metadata": {"product": "billing"},
"order_id": 0,
"page_content": "Invoices are generated on the first day of each month. Finance staff can export invoices as PDF or CSV files from the Billing page.",
"path": null,
"score": 0.8752695693762373,
"version": 1790683502431906
},
{
"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": 1.0389346220209017,
"version": 1790683504447128
}
]
}
- Permissions. Read and execute on the pipeline, and every named classification in the classification allow-list, as for REST search.
- Errors. The errors of REST search, such as a search index that is still
building(HTTP 409) or a search type without the required index (HTTP 400), return -32602 with the REST message and details. More than one entry insearch_index_idsfor a type other thanhybridreturns -32602only hybrid searches combine several search indexers. Akof 0 returns -32602`k` must be greater than 0. Formmr, afetch_kof 0 returns`fetch_k` must be greater than 0, afetch_ksmaller thankreturns`fetch_k` cannot be smaller than `k`and alambda_multoutside 0 to 1 returns`lambda_mult` must be between 0 and 1, each with code -32602 and nodata. A pipeline that does not exist, or on which the key lacks read and execute permission, returns -32002Pipeline not found.
Document tools
list_paths
list_paths lists the paths of a pipeline's documents and the number of documents at each path, in byte order, with cursor pages. The tool corresponds to GET /pipelines/{id}/paths, described in Document paths.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
path | String | No | >, every path | A path pattern that selects the paths to list |
limit | Integer | No | 100 | The maximum number of paths, from 1 to 1,000. A smaller value counts as 1 and a larger value as 1,000. |
cursor | String | No | None | The next_cursor of the previous page |
Each entry of results holds path and documents, the number of current document versions at the path. When the page is full, next_cursor holds the last path of the page. For the support-kb pipeline with the documents of Organize and search documents by path, the structuredContent is the following:
{
"results": [
{"documents": 1, "path": "kb.accounts.sso"},
{"documents": 1, "path": "kb.billing.payment-methods"},
{"documents": 1, "path": "kb.billing.tax.vat"}
]
}
- Permissions. Read on the pipeline. The counts include only the classifications of the key's allow-list.
- Errors. An invalid pattern returns -32602
`path` is not a valid path: <reason>.
list_documents
list_documents lists the current version of each document of a pipeline, with cursor pages. The tool corresponds to GET /pipelines/{id}/documents.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
limit | Integer | No | 10 | The maximum number of documents to return |
cursor | String | No | None | The next_cursor of the previous page |
external_identifier | String | No | None | Returns only the document with this external identifier |
status | String | No | None | Returns only the documents with this status: pending, success, failed or canceled |
path | String | No | Documents without a path | A path pattern. Without the argument, the list includes only the documents without a path, and the pattern > lists the documents with a path. |
metadata | Object | No | No filter | A metadata filter in the language of Filter operators |
The output holds results, an array of document objects, and next_cursor when a further page may exist.
- Permissions. Read on the pipeline. The list includes only the documents of the classifications in the key's allow-list and the classifications that they inherit.
get_document
get_document returns the current version of one document of a pipeline. The tool corresponds to GET /pipelines/{id}/documents/{document_id}.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
document_id | String | Yes | None | The document identifier, a UUID |
The output is one document object. The structuredContent for the kb-refund-policy document of First search:
{
"classification": "internal",
"created_at": "2026-09-29T12:05:04.447128Z",
"document_id": "01a0ed0d-df3f-7f80-9a1b-2c3d4e5f6a7b",
"expired_at": null,
"external_identifier": "kb-refund-policy",
"message": null,
"metadata": {"product": "billing"},
"path": null,
"pipeline_id": "c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06",
"resource_uri": "f4ai://pipelines/c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06/documents/01a0ed0d-df3f-7f80-9a1b-2c3d4e5f6a7b",
"status": "success",
"version": 1790683504447128
}
- Permissions. Read on the pipeline, and the document's classification in the allow-list.
- Errors. A document that does not exist, or whose versions have all expired, returns -32002
Document not found.
get_document_fragments
get_document_fragments returns the fragments of the current version of a document, in document order, with cursor pages. A client reads the text around a search result with this tool. The tool corresponds to GET /pipelines/{id}/documents/{document_id}/fragments with contents=true.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
document_id | String | Yes | None | The document identifier, a UUID |
limit | Integer | No | 20 | The maximum number of fragments to return |
cursor | String | No | None | The next_cursor of the previous page |
The output holds results, an array of fragments ordered by order_id with score set to null, and next_cursor when a further page may exist.
- Permissions. Read and execute on the pipeline, and the document's classification in the allow-list.
- Errors. A document that does not exist, or whose current version has expired, returns -32002
Document not found.
get_document_versions
get_document_versions lists the versions of a document, newest first. The tool corresponds to GET /documents/{document_id}/versions.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
document_id | String | Yes | None | The document identifier, a UUID |
include_expired | Boolean | No | true | Includes the expired versions |
The output holds results, an array of document objects, one for each version, without page information.
- Permissions. Read on the document's pipeline. The array is empty for a document whose classification is outside the allow-list.
- Errors. A document that does not exist, including a deleted document, returns -32002
Document not found, withdataset to{"id": "<identifier>"}.
add_document
add_document adds a document, or a new version of a document, to a pipeline. The tool corresponds to POST /pipelines/{id}/documents, described in Documents, versions and fragments.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
classification | String | Yes | None | The classification of the document, one that the pipeline defines |
contents | String | Yes | None | The text of the document |
metadata | Object | No | None | The metadata of the document, which follows the pipeline schema |
path | String | No | No path | The path of the new version, such as kb.billing.refunds. A new version does not inherit the path of the previous version. |
external_identifier | String | No | None | The client application's identifier. A document with the external identifier of an existing document becomes a new version of that document. |
expire_older_versions | Boolean | No | true | Expires the previous versions of the document when the new version is added |
The document is processed with the pipeline's default text splitter; the tool has no text_splitter_id argument. The output is the new document object with status set to pending. The workers process the document asynchronously, and the document appears in searches when get_document reports success.
- Permissions. Execute on the pipeline, execute on the text splitter, and the document's classification itself in the allow-list.
- Errors. Metadata that does not follow the schema and a classification outside the allow-list return -32602 with the REST message and details. An invalid path returns -32602 without data, with a message that names the path, as in
Invalid parameter: Invalid path `kb.Billing`: expected labels of lowercase letters, digits, `-` and `_` separated by periods. A classification that the pipeline does not define returns -32002Classification not foundwithout data.
expire_document
expire_document expires the current version of a document. The expired document no longer appears in searches or document lists, and the versions remain readable with get_document_versions. The tool corresponds to DELETE /pipelines/{id}/documents/{document_id} with expire=true.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
document_id | String | Yes | None | The document identifier, a UUID |
The output is {"document_id": "<document id>", "expired": true}.
- Permissions. Write and execute on the pipeline, and the document's classification in the allow-list.
delete_document
delete_document deletes a document and every version of the document. The deletion cannot be undone. The tool corresponds to DELETE /pipelines/{id}/documents/{document_id}.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
pipeline_id | String | Yes | None | The pipeline identifier, a UUID |
document_id | String | Yes | None | The document identifier, a UUID |
The output is {"deleted": true, "document_id": "<document id>"}. A second call for the same document returns -32002 with the REST message.
- Permissions. Read, write and execute on the pipeline, and the document's classification in the allow-list.
Taxonomy tools
list_taxonomies
list_taxonomies lists the taxonomies that the key can read, with offset pages. The tool corresponds to GET /taxonomies, and Metadata, filters and taxonomies describes taxonomies.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
limit | Integer, 1 to 1,000 | No | 10 | The maximum number of taxonomies to return |
offset | Integer, 0 or greater | No | 0 | The number of taxonomies to skip |
query | String | No | None | Returns only the taxonomies whose name contains the text |
Each entry of results holds taxonomy_id, name and description.
- Permissions. Read on each taxonomy returned.
get_taxonomy_entries
get_taxonomy_entries lists the entries of one taxonomy, with offset pages. The tool corresponds to GET /taxonomies/{id}/entries.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
taxonomy_id | String | Yes | None | The taxonomy identifier, a UUID |
limit | Integer, 1 to 1,000 | No | 50 | The maximum number of entries to return |
offset | Integer, 0 or greater | No | 0 | The number of entries to skip |
parent | String | No | None | Returns only the entries whose parent term contains the text |
child | String | No | None | Returns only the entries whose child term contains the text |
Each entry of results holds parent, parent_value, child and child_value.
- Permissions. Read on the taxonomy.
Agent tools
list_agents
list_agents lists the agents that the key can read, with offset pages. The tool corresponds to GET /agents, and Agents and prompt templates describes agents.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
limit | Integer, 1 to 1,000 | No | 10 | The maximum number of agents to return |
offset | Integer, 0 or greater | No | 0 | The number of agents to skip |
query | String | No | None | Returns only the agents whose name contains the text |
| Field | Type | Description |
|---|---|---|
agent_id | String | The agent identifier |
name | String | The agent name, which is also the name of the agent's MCP prompt |
description | String or null | The agent description |
input_variables | Array of strings | The names of the query placeholders, in alphabetical order. agent_search and run_agent take a value for each name in inputs. |
retrievals | Array of strings | The names of the retrieval placeholders, in the order of the agent. agent_search returns the fragments of each, and filters takes a filter for each. |
For the support-answers agent of Agents and prompt templates, input_variables is ["question"] and retrievals is ["context"].
- Permissions. Read on each agent returned.
list_llms
list_llms lists the LLMs that the key can read, with offset pages. The tool corresponds to GET /llms. The arguments are those of list_agents. Each entry of results holds llm_id, name, description and model, the model name that the LLM requests from the model server.
- Permissions. Read on each LLM returned.
agent_search
agent_search runs the retrieval placeholders of an agent without calling an LLM, and returns the fragments of each placeholder. The tool corresponds to POST /agents/{id}/search.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | String | Yes | None | The agent identifier, a UUID |
pipeline_id | String | Yes | None | The pipeline that the retrieval placeholders search |
inputs | Object | Yes | None | A value for each input variable of the agent, such as {"question": "How do customers get their money back?"} |
classifications | Array of strings | Yes | None | The classifications that the reader holds, matched as in search_knowledge |
exact_classifications | Boolean | No | false | Searches only the named classifications, as in search_knowledge |
path | String | No | Documents without a path | A path pattern that applies to every retrieval placeholder |
filters | Object | No | No filter | An object that maps the name of a retrieval placeholder to a metadata filter for that placeholder |
The output object maps the name of each retrieval placeholder to an array of fragments, with scores. For the support-answers agent, the output has one field, context.
- Permissions. Execute on the agent and on the pipeline, and the named classifications in the allow-list.
- Errors. A license that is not valid returns -32602
Invalid license: <reason>.
run_agent
run_agent runs an agent: the API server retrieves the fragments, fills the prompt template, sends the messages to the LLM and returns the complete answer with the fragments that the LLM received. The tool corresponds to POST /agents/{id}/execute with "stream": false, and with "tracing": true unless sources is false.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
llm_id | String | Yes | None | The LLM that generates the answer, from list_llms |
temperature | Number | No | The model server's default | The sampling temperature |
sources | Boolean | No | true | Returns the fragments that the LLM received and the identifier of the execution trace |
attributions | Boolean | No | false | Attributes each sentence of the answer to the fragments that support the sentence. The argument applies only when sources is true. |
Every argument of agent_search | agent_id, pipeline_id, inputs, classifications, exact_classifications, path and filters, with the same meaning |
The output object has the following fields:
| Field | Type | Description |
|---|---|---|
answer | String | The text of the answer |
sources | Object | The fragments that the LLM received, by retrieval placeholder name, without page_content. get_document_fragments reads the text around a fragment. Absent when sources is false. |
tracing_id | String | The identifier of the execution trace, which GET /tracing/{id} returns to the same API key for 60 minutes. Absent when sources is false. |
attributions | Array | One entry for each sentence of the answer, with the fragments that support the sentence, as described in Answer attributions. Present only when attributions is true. |
The prompt does not label the retrieved fragments, so the answer itself cites no sources. A client that shows sources takes the sources from sources or from attributions.
- Permissions. Execute on the agent, the pipeline and the LLM, and the named classifications in the allow-list.
- Errors. A failure of the model server returns -32603
The LLM call failed; see the server logs, and the API server log records the cause. A license that is not valid returns -32602Invalid license: <reason>.
Prompts
Each agent that the key can read is also an MCP prompt with the name of the agent. A client that gets a prompt receives the agent's messages with the retrieved fragments inserted, and generates the answer with the client's own language model. No Foundation4 LLM takes part.
prompts/list returns the agents in pages of 50, with nextCursor set when the page is full. Each prompt has the following fields:
| Field | Value |
|---|---|
name | The agent name |
title | The agent name |
description | The agent description |
arguments | pipeline_id (required), classifications (required), path (optional) and one required argument for each input variable of the agent, without a description |
The classifications argument is one string with the classification names separated by commas, such as internal,billing, because MCP prompt arguments are strings. The classifications are matched hierarchically. An empty path argument counts as no path.
prompts/get names the prompt and the arguments, runs the retrieval placeholders and returns the include messages of the agent with every placeholder replaced. The fragments of a retrieval placeholder are inserted as their texts, joined by line breaks. MCP prompts have no system role, so system messages are returned with the role user. The following request gets the support-answers prompt:
{
"jsonrpc": "2.0",
"id": 5,
"method": "prompts/get",
"params": {
"name": "support-answers",
"arguments": {
"pipeline_id": "c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06",
"classifications": "internal",
"question": "How do customers get their money back?"
}
}
}
The result for the support-answers agent on the support-kb pipeline:
{
"description": "Answers support questions from the product knowledge base",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Answer using only the reference text. If the reference text does not contain the answer, say that the answer is not available."
}
},
{
"role": "user",
"content": {
"type": "text",
"text": "Reference text:\nRefunds for annual plans are prorated. Support agents must record the refund reason in the ticket before approving a refund.\nInvoices are generated on the first day of each month. Finance staff can export invoices as PDF or CSV files from the Billing page.\nTo reset a password, open Settings, choose Security and select Reset password. A reset link is sent to the registered email address and expires after 30 minutes.\n\nQuestion: How do customers get their money back?"
}
}
]
}
- Permissions.
prompts/listrequires read on each agent listed.prompts/getrequires read and execute on the agent, execute on the pipeline, and the named classifications in the allow-list. - Errors. An unknown prompt name returns -32602
Prompt not foundwithdataset to{"name": "<name>"}. A missingpipeline_idreturns -32602Missing argument `pipeline_id`, and a missing input variable returns -32602Invalid parameterwith the missing names indata. An invalid cursor ofprompts/listreturns -32602Invalid cursor.
Resources
The text of each document is an MCP resource, so that a client can attach a source document to a conversation. The server does not list documents, because a pipeline can hold millions: resources/list returns an empty list, and resources/templates/list returns one template:
{
"uriTemplate": "f4ai://pipelines/{pipeline_id}/documents/{document_id}",
"name": "document",
"title": "Pipeline document",
"description": "The text of a pipeline document (its current version), assembled from its fragments",
"mimeType": "text/plain"
}
The document tools return the URI of each document in resource_uri. resources/read with that URI returns one text content with the fragments of the current version, in document order, joined by line breaks:
{
"contents": [
{
"uri": "f4ai://pipelines/c4a7e2d1-6b3f-4f8e-a2d9-7e1b5c3f9a06/documents/01a0ed0d-df3f-7f80-9a1b-2c3d4e5f6a7b",
"mimeType": "text/plain",
"text": "Refunds for annual plans are prorated. Support agents must record the refund reason in the ticket before approving a refund."
}
]
}
The text is assembled from the stored fragments, not from the submitted contents. A document that is still pending has no fragments and returns an empty text, and a text splitter that overlaps fragments repeats the overlapping text.
- Permissions. Read and execute on the pipeline, and the document's classification in the allow-list.
- Errors. A URI of another form returns -32002
Unknown resource, with the expected form indata. A document that does not exist, or whose versions have all expired, returns -32002Document not found.