Skip to main content

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:

FieldValueDescription
protocolVersionThe revision named in the request, or 2025-11-25The 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.namefoundation4aiA fixed name. The branding name configuration does not change the value.
serverInfo.titleFoundation4.aiA fixed display name. The branding name configuration does not change the value.
serverInfo.versionThe Foundation4 release, such as 1.1.0An image built with a build identifier reports the release followed by + and the identifier
instructionsThe text belowA 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.

ToolDescription sent to the client
add_documentAdd 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_searchRun an agent's retrieval only: the fragments each of its retrieval steps finds in a pipeline, without calling an LLM
delete_documentDelete a document and all its versions. This cannot be undone: prefer expire_document to keep its history.
expire_documentExpire a document: it is no longer returned by searches, but its versions are kept and can still be read
get_documentGet a document of a pipeline: its current version, classification, metadata and processing status
get_document_fragmentsRead a document's fragments in order, e.g. to see the context around a search result
get_document_versionsList the versions of a document, newest first
get_pipelineGet a pipeline: its search indexes and the JSON schema of its documents' metadata, which metadata filters use
get_pipeline_classificationsList the document classifications of a pipeline you can read, and which classifications inherit from which
get_pipelinesList the pipelines (knowledge bases) you can access, with their search indexes
get_taxonomy_entriesList the entries of a taxonomy: parent terms and the child terms they relate to
list_agentsList 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_documentsList the documents of a pipeline, optionally filtered by external identifier, status or metadata
list_llmsList the LLMs agents can run with (see run_agent)
list_pathsList 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_taxonomiesList the taxonomies: vocabularies that map terms to related terms, e.g. to expand metadata filters
run_agentRun 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_knowledgeSearch 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.

ToolreadOnlyHintdestructiveHintidempotentHintopenWorldHint
add_documentfalsefalsefalsefalse
delete_document, expire_documentfalsetruetruefalse
run_agentfalsefalsefalsetrue
Every other tooltruefalsetruefalse

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:

FieldTypeDescription
contentArrayOne text block, {"type": "text", "text": "<JSON>"}, whose text is the tool output serialized as a JSON string
structuredContentObjectThe tool output as a JSON object, described by the outputSchema of the tool
isErrorBooleanfalse

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.

FieldTypeDescription
pipeline_idStringThe pipeline identifier
nameStringThe pipeline name
descriptionString or nullThe pipeline description
default_vector_index_idString or nullThe identifier of the default vector index, which the REST API returns as default_vector_embedding_index_id
default_text_search_index_idString or nullThe identifier of the default text index, a full-text or a BM25 index
search_indexersArrayThe search indexes of the pipeline, ordered by identifier, described in Search index
default_text_splitter_idStringThe identifier of the pipeline's default text splitter
schemaObjectget_pipeline only: the JSON Schema of the documents' metadata, which metadata filters and add_document follow

Search index​

FieldTypeDescription
idStringThe identifier of the search index, the value that search_index_ids of search_knowledge takes
kindStringvchord 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_modelString or nullThe name of the embedding model of a vector index, null for a text index
statusStringready 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.

FieldTypeDescription
idStringThe fragment identifier
classificationStringThe classification of the fragment's document
metadataObjectThe metadata of the fragment's document
pathString or nullThe path of the fragment's document version, or null for a document without a path
document_idStringThe identifier of the document
page_contentStringThe decrypted text of the fragment. The field is absent when the text is empty.
versionIntegerThe document version, in microseconds since the Unix epoch
expired_atString or nullThe time at which the document version expired, null for a current version
scoreNumber or nullThe 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_idIntegerThe 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:

FieldTypeDescription
document_idStringThe document identifier, which the REST API returns as id
versionIntegerThe document version, in microseconds since the Unix epoch
pipeline_idStringThe identifier of the pipeline
classificationStringThe classification of the document
external_identifierString or nullThe client application's identifier for the document
metadataObjectThe metadata of the document
pathString or nullThe path of the document version, or null
statusStringpending, success, failed or canceled, as described in Ingest documents reliably
messageString or nullThe reason for a failed status
created_atStringThe creation time of the version, in RFC 3339 format
expired_atString or nullThe time at which the version expired
resource_uriStringThe 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_documents and get_document_fragments return next_cursor beside results when a further page may exist. A call with cursor set 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_agents and list_llms take limit and offset and return no page information. get_pipelines also returns total, the number of matching pipelines across all pages. A client reads the next page with offset increased by limit, until a call returns fewer objects than limit. A limit outside 1 to 1,000 returns -32602 Pagination error, with data set to {"error": "limit must be between 1 and 1000, got 0"} for a limit of 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:

CauseText
A required argument is missingfailed to deserialize parameters: missing field `pipeline_id`
An argument has the wrong typefailed to deserialize parameters: invalid type: string "5", expected u16
search_type has an undefined valuefailed 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:

CodeMeaningErrors
-32602Invalid parametersAn 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
-32002Resource not foundPipeline not found and Document not found, with data set to {"id": "<identifier>"}, and every REST error with HTTP status 404
-32603Internal errorServer-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.

StatusBodyCause
400Bad Request: Unsupported MCP-Protocol-Version: <value>The MCP-Protocol-Version header names a revision that the server does not support
400JSON-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
400JSON-RPC error -32600 stateless server does not accept JSON-RPC responsesThe body is a JSON-RPC response or error. The server sends no requests to clients, so no response is expected.
400JSON-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
401JSON error body, such as Unauthorized: No API Key specified.The API key headers are missing or invalid, as described in Errors
403Forbidden: Host header is not allowedThe deployment restricts the host names of the MCP server, and the Host header names another host, as described in MCP server
404JSON error body Not foundA path under /mcp, such as /mcp/
405JSON error body Method not allowedA method other than POST, such as GET or DELETE. The Allow header names POST.
406Not Acceptable: Client must accept both application/json and text/event-streamThe Accept header of a POST request does not list both types
413Payload Too Large: request body exceeds 4194304 bytesThe body is larger than 4 MiB
415Unsupported Media Type: Content-Type must be application/jsonThe Content-Type header is not application/json
415fail 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.

ArgumentTypeRequiredDefaultDescription
limitInteger, 1 to 1,000No10The maximum number of pipelines to return
offsetInteger, 0 or greaterNo0The number of pipelines to skip
queryStringNoNoneReturns 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 results array.
  • Errors. Argument type errors, such as a negative limit, return a result with isError set to true.

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}.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
FieldTypeDescription
classificationsArray of stringsThe classifications of the pipeline that the key's classification allow-list names, or every classification with the allow-list *
hierarchyArray of pairs of stringsThe 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
queryStringYesNoneThe search text. latest ignores the text.
classificationsArray of stringsYesNoneThe 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_classificationsBooleanNofalseSearches only the named classifications, without inheritance, and returns an error when the pipeline does not define a named classification
search_typeStringNosimilarityThe search type, from the table below
search_index_idsArray of stringsNoThe default indexesThe 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.
kInteger, 1 to 65535No5The number of fragments to return
thresholdNumberNoNoneFor similarity and mmr, the maximum distance from the query. For text, the minimum score. hybrid and latest ignore the argument.
fetch_kInteger, k to 65535No10, or k when k is greatermmr only: the number of candidates from which MMR search selects k fragments
lambda_multNumber, 0 to 1No0.5mmr only: the balance between relevance (1) and diversity (0)
pathStringNoDocuments without a pathA path pattern, such as kb.billing.>, described in Document paths. Without the argument, the search covers only the documents without a path.
filtersObjectNoNo filterA metadata filter in the language of Filter operators

The search types of the tool correspond to the search types of the REST API:

search_typeREST typeSearch
similaritysimilarityThe k fragments closest in meaning to the query
mmrmmrMaximal marginal relevance (MMR) search: k fragments selected from the fetch_k closest fragments for relevance and diversity
textsearchFull-text search on a full-text index or a BM25 index
hybridhybridThe result lists of several search indexes, fused by reciprocal rank fusion
latesthistoryThe 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_strategy argument.
  • MMR candidates. Without fetch_k, MMR search draws on at least k candidates, 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 in search_index_ids for a type other than hybrid returns -32602 only hybrid searches combine several search indexers. A k of 0 returns -32602 `k` must be greater than 0. For mmr, a fetch_k of 0 returns `fetch_k` must be greater than 0, a fetch_k smaller than k returns `fetch_k` cannot be smaller than `k` and a lambda_mult outside 0 to 1 returns `lambda_mult` must be between 0 and 1, each with code -32602 and no data. A pipeline that does not exist, or on which the key lacks read and execute permission, returns -32002 Pipeline 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
pathStringNo>, every pathA path pattern that selects the paths to list
limitIntegerNo100The maximum number of paths, from 1 to 1,000. A smaller value counts as 1 and a larger value as 1,000.
cursorStringNoNoneThe 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
limitIntegerNo10The maximum number of documents to return
cursorStringNoNoneThe next_cursor of the previous page
external_identifierStringNoNoneReturns only the document with this external identifier
statusStringNoNoneReturns only the documents with this status: pending, success, failed or canceled
pathStringNoDocuments without a pathA path pattern. Without the argument, the list includes only the documents without a path, and the pattern > lists the documents with a path.
metadataObjectNoNo filterA 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}.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
document_idStringYesNoneThe 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
document_idStringYesNoneThe document identifier, a UUID
limitIntegerNo20The maximum number of fragments to return
cursorStringNoNoneThe 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.

ArgumentTypeRequiredDefaultDescription
document_idStringYesNoneThe document identifier, a UUID
include_expiredBooleanNotrueIncludes 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, with data set 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
classificationStringYesNoneThe classification of the document, one that the pipeline defines
contentsStringYesNoneThe text of the document
metadataObjectNoNoneThe metadata of the document, which follows the pipeline schema
pathStringNoNo pathThe path of the new version, such as kb.billing.refunds. A new version does not inherit the path of the previous version.
external_identifierStringNoNoneThe client application's identifier. A document with the external identifier of an existing document becomes a new version of that document.
expire_older_versionsBooleanNotrueExpires 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 -32002 Classification not found without 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.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
document_idStringYesNoneThe 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}.

ArgumentTypeRequiredDefaultDescription
pipeline_idStringYesNoneThe pipeline identifier, a UUID
document_idStringYesNoneThe 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.

ArgumentTypeRequiredDefaultDescription
limitInteger, 1 to 1,000No10The maximum number of taxonomies to return
offsetInteger, 0 or greaterNo0The number of taxonomies to skip
queryStringNoNoneReturns 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.

ArgumentTypeRequiredDefaultDescription
taxonomy_idStringYesNoneThe taxonomy identifier, a UUID
limitInteger, 1 to 1,000No50The maximum number of entries to return
offsetInteger, 0 or greaterNo0The number of entries to skip
parentStringNoNoneReturns only the entries whose parent term contains the text
childStringNoNoneReturns 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.

ArgumentTypeRequiredDefaultDescription
limitInteger, 1 to 1,000No10The maximum number of agents to return
offsetInteger, 0 or greaterNo0The number of agents to skip
queryStringNoNoneReturns only the agents whose name contains the text
FieldTypeDescription
agent_idStringThe agent identifier
nameStringThe agent name, which is also the name of the agent's MCP prompt
descriptionString or nullThe agent description
input_variablesArray of stringsThe names of the query placeholders, in alphabetical order. agent_search and run_agent take a value for each name in inputs.
retrievalsArray of stringsThe 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 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.

ArgumentTypeRequiredDefaultDescription
agent_idStringYesNoneThe agent identifier, a UUID
pipeline_idStringYesNoneThe pipeline that the retrieval placeholders search
inputsObjectYesNoneA value for each input variable of the agent, such as {"question": "How do customers get their money back?"}
classificationsArray of stringsYesNoneThe classifications that the reader holds, matched as in search_knowledge
exact_classificationsBooleanNofalseSearches only the named classifications, as in search_knowledge
pathStringNoDocuments without a pathA path pattern that applies to every retrieval placeholder
filtersObjectNoNo filterAn 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.

ArgumentTypeRequiredDefaultDescription
llm_idStringYesNoneThe LLM that generates the answer, from list_llms
temperatureNumberNoThe model server's defaultThe sampling temperature
sourcesBooleanNotrueReturns the fragments that the LLM received and the identifier of the execution trace
attributionsBooleanNofalseAttributes each sentence of the answer to the fragments that support the sentence. The argument applies only when sources is true.
Every argument of agent_searchagent_id, pipeline_id, inputs, classifications, exact_classifications, path and filters, with the same meaning

The output object has the following fields:

FieldTypeDescription
answerStringThe text of the answer
sourcesObjectThe 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_idStringThe identifier of the execution trace, which GET /tracing/{id} returns to the same API key for 60 minutes. Absent when sources is false.
attributionsArrayOne 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 -32602 Invalid 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:

FieldValue
nameThe agent name
titleThe agent name
descriptionThe agent description
argumentspipeline_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/list requires read on each agent listed. prompts/get requires 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 found with data set to {"name": "<name>"}. A missing pipeline_id returns -32602 Missing argument `pipeline_id` , and a missing input variable returns -32602 Invalid parameter with the missing names in data. An invalid cursor of prompts/list returns -32602 Invalid 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 in data. A document that does not exist, or whose versions have all expired, returns -32002 Document not found.