Tool Reference

MCP tool names

The tables below list every tool the MCP server can expose, by its MCP tool name. MCP tool name is the name an agent calls and the name you pass to tools_to_register:

configure_mcp_server(
    mcp_server_instance=mcp,
    tools_to_register={"list_pipelines", "get_pipeline", "grep_object_store"},
)

Note

A few MCP tool names differ from the Python function that implements them (the function is what appears under Tool base functions below). Always register the MCP tool name listed in this table:

MCP tool name	Implemented by Python function
search_component_definitions	search_component_definition
get_from_object_store	create_get_from_object_store
get_slice_from_object_store	create_get_slice_from_object_store
grep_object_store	create_grep_object_store
sed_object_store	create_sed_object_store
yq_object_store	create_yq_object_store
search_docs	get_docs_search_tool

Pipelines

The Memory column describes how a tool interacts with the object store (see MCP server concepts):

• explorable: The tool's output is stored and returned as an @obj_id reference.
• referenceable: The tool accepts @obj_id references as parameters.
• none: The tool returns its output directly.

MCP tool name	Workspace	Memory	Description
list_pipelines	required	explorable	List all pipelines in the workspace.
get_pipeline	required	explorable	Fetch a pipeline's configuration and status.
create_pipeline	required	explorable, referenceable	Create a new pipeline from a YAML configuration.
validate_pipeline	required	explorable, referenceable	Validate a YAML configuration without saving it.
deploy_pipeline	required	explorable	Deploy a pipeline and wait for it to become available.
get_pipeline_logs	required	explorable	Fetch a deployed pipeline's logs.
debug_pipeline	required	explorable, referenceable	Run a YAML configuration in debug mode, optionally breaking at a component or resuming from a snapshot.
search_pipeline	required	explorable	Run a query against a deployed pipeline.
search_pipeline_with_filters	required	explorable	Run a query with metadata filters.
search_pipeline_with_params	required	explorable	Run a query with component-level parameter overrides.

Pipeline versions

MCP tool name	Workspace	Memory	Description
list_pipeline_versions	required	explorable	List a pipeline's saved versions.
get_pipeline_version	required	explorable	Fetch a specific pipeline version.
create_pipeline_version	required	explorable, referenceable	Save the current configuration as a new version.
patch_pipeline_version	required	explorable, referenceable	Apply a partial update to a pipeline version.
restore_pipeline_version	required	explorable, referenceable	Restore a pipeline to an earlier version.

Indexes

MCP tool name	Workspace	Memory	Description
list_indexes	required	explorable	List all indexes in the workspace.
get_index	required	explorable	Fetch an index's configuration.
create_index	required	explorable, referenceable	Create a new index from a YAML configuration.
update_index	required	explorable, referenceable	Update an existing index's configuration.
validate_index	required	explorable, referenceable	Validate an index configuration without saving it.
deploy_index	required	explorable	Deploy an index.

Search history and traces

MCP tool name	Workspace	Memory	Description
list_search_history	required	explorable	List search history across the workspace.
list_pipeline_search_history	required	explorable	List search history for one pipeline.
list_pipeline_traces	required	explorable	List lightweight run-trace summaries for a pipeline.
get_pipeline_trace	required	explorable	Fetch the full execution trace for one query, including component spans with input/output and logs.
get_pipeline_trace_span_tags	required	explorable	Fetch the tags of a single span, to inspect one component's input/output cheaply.
get_pipeline_trace_logs	required	explorable	Fetch only the log entries for one run.

Templates

MCP tool name	Workspace	Memory	Description
list_templates	required	explorable	List available pipeline templates.
get_template	required	explorable	Fetch a specific pipeline template.
search_templates	required	explorable	Search templates by semantic similarity.

Haystack components

MCP tool name	Workspace	Memory	Description
list_component_families	not needed	explorable	List the available Haystack component families.
get_component_definition	not needed	explorable	Fetch a component's initialization parameters and I/O.
search_component_definitions	not needed	explorable	Search component definitions by semantic similarity.
get_custom_components	not needed	explorable	List the custom components installed for the organization.
run_component	not needed	explorable, referenceable	Run a single component in isolation to test its behavior.

Custom components

MCP tool name	Workspace	Memory	Description
list_custom_component_installations	required	explorable	List custom component installations.
get_latest_custom_component_installation_logs	required	explorable	Fetch logs for the most recent custom component installation.

Workspaces, secrets and models

MCP tool name	Workspace	Memory	Description
list_workspaces	not needed	explorable	List the workspaces available to the API key.
get_workspace	not needed	explorable	Fetch a workspace's details.
create_workspace	not needed	explorable	Create a new workspace.
list_secrets	not needed	explorable	List the secrets available to the organization.
get_secret	not needed	explorable	Fetch a secret's metadata by ID.
get_models	required	explorable	List models available for use in pipelines.

Object store

These tools let an agent inspect and manipulate stored objects without pulling them into context. See Tool output truncation and exploration.

MCP tool name	Workspace	Memory	Description
get_from_object_store	not needed	none	Fetch a stored object, or a nested value by path.
get_slice_from_object_store	not needed	none	Extract a range from a stored string or list.
grep_object_store	not needed	none	Regex-search a stored string and return matches with context.
sed_object_store	not needed	none	Regex-replace within a stored string, storing the result as a new object.
yq_object_store	not needed	none	Query or transform stored YAML/JSON with a jq filter expression.

Documentation and skills

MCP tool name	Workspace	Memory	Description
search_docs	not needed	none	Search the Haystack Enterprise Platform documentation. Requires docs search to be configured on the server.
load_skill	not needed	none	Load a bundled skill containing detailed guidance for a specific task.

Tool base functions

The Python functions that implement the tools above. Their docstrings are what the calling LLM receives as the tool description.

deepset_mcp.tools.get_latest_custom_component_installation_logs async

get_latest_custom_component_installation_logs(
    *, client: AsyncClientProtocol, workspace: str
) -> str

Get the logs from the latest custom component installation.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use.	required
workspace	str	The workspace to operate in.	required

Returns:

Type	Description
str	The latest installation logs or error message.

deepset_mcp.tools.list_custom_component_installations async

list_custom_component_installations(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    limit: int = 20,
    after: str | None = None,
) -> PaginatedResponse[CustomComponentInstallation] | str

List custom component installations.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use.	required
workspace	str	The workspace to operate in.	required
limit	int	Maximum number of installations to return per page.	20
after	str | None	The cursor to fetch the next page of results.	None

Returns:

Type	Description
PaginatedResponse[CustomComponentInstallation] | str	Custom component installations or error message.

deepset_mcp.tools.search_docs async

search_docs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query: str,
) -> str

Search deepset documentation using a dedicated docs pipeline.

Uses the specified pipeline to perform a search with the given query against the deepset documentation. Before executing the search, checks if the pipeline is deployed (status = DEPLOYED). Returns search results in a human-readable format.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name for the docs pipeline.	required
pipeline_name	str	Name of the pipeline to use for doc search.	required
query	str	The search query to execute.	required

Returns:

Type	Description
str	A string containing the formatted search results or error message.

deepset_mcp.tools.get_component_definition async

get_component_definition(
    *,
    client: AsyncClientProtocol,
    component_type: str,
    haystack_version: str | None = None,
) -> ComponentDefinition | str

Returns the definition of a specific Haystack component.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use	required
component_type	str	Fully qualified component type (e.g. haystack.components.routers.conditional_router.ConditionalRouter)	required
haystack_version	str | None	Optional version of Haystack to use. Pass the same version as specified in the pipeline yaml's dependencies section for the haystack-ai package.	None

Returns:

Type	Description
ComponentDefinition | str	ComponentDefinition model or error message string

deepset_mcp.tools.get_custom_components async

get_custom_components(
    *,
    client: AsyncClientProtocol,
    haystack_version: str | None = None,
) -> ComponentDefinitionList | str

Get a list of all installed custom components.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use.	required
haystack_version	str | None	Optional version of Haystack to use. Pass the same version as specified in the pipeline yaml's dependencies section for the haystack-ai package.	None

Returns:

Type	Description
ComponentDefinitionList | str	ComponentDefinitionList model or error message string.

deepset_mcp.tools.list_component_families async

list_component_families(
    *,
    client: AsyncClientProtocol,
    haystack_version: str | None = None,
) -> ComponentFamilyList | str

Lists all Haystack component families that are available on deepset.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use	required
haystack_version	str | None	Optional version of Haystack to use. Pass the same version as specified in the pipeline yaml's dependencies section for the haystack-ai package.	None

Returns:

Type	Description
ComponentFamilyList | str	ComponentFamilyList model or error message string

deepset_mcp.tools.run_component async

run_component(
    *,
    client: AsyncClientProtocol,
    component_type: str,
    init_params: dict[str, Any] | None = None,
    input_data: dict[str, Any] | None = None,
    input_types: dict[str, str] | None = None,
    haystack_version: str | None = None,
) -> dict[str, Any] | str

Run a Haystack component with the given parameters.

This tool allows you to execute a Haystack component by providing its type and initialization parameters, then passing input data to get results. Use this to test components and see how they would work in your pipeline.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use	required
component_type	str	The type of component to run (e.g., "haystack.components.builders.prompt_builder.PromptBuilder")	required
init_params	dict[str, Any] | None	Initialization parameters for the component	None
input_data	dict[str, Any] | None	Input data for the component	None
input_types	dict[str, str] | None	Optional type information for inputs (inferred if not provided). For custom types use the full import path (e.g. haystack.dataclasses.document.Document for Document)	None
haystack_version	str | None	Optional version of Haystack to use for the component. Pass the same version as specified in the pipeline yaml's dependencies section for the haystack-ai package.	None

Returns:

Type	Description
dict[str, Any] | str	Dictionary containing the component's outputs or error message string

deepset_mcp.tools.search_component_definition async

search_component_definition(
    *,
    client: AsyncClientProtocol,
    query: str,
    model: ModelProtocol,
    top_k: int = 5,
    haystack_version: str | None = None,
) -> ComponentSearchResults | str

Searches for components based on name or description using semantic similarity.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use	required
query	str	The search query	required
model	ModelProtocol	The model to use for computing embeddings	required
top_k	int	Maximum number of results to return (default: 5)	5
haystack_version	str | None	Optional version of Haystack to use. Pass the same version as specified in the pipeline yaml's dependencies section for the haystack-ai package.	None

Returns:

Type	Description
ComponentSearchResults | str	ComponentSearchResults model or error message string

deepset_mcp.tools.create_index async

create_index(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    index_name: str,
    yaml_configuration: str,
    description: str | None = None,
) -> dict[str, str | Index] | str

Creates a new index within your Haystack Enterprise Platform workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	Deepset API client to use.	required
workspace	str	Workspace in which to create the index.	required
index_name	str	Unique name of the index to create.	required
yaml_configuration	str	YAML configuration to use for the index.	required
description	str | None	Description of the index to create.	None

Returns:

Type	Description
dict[str, str | Index] | str	A message and the created index, or an error message.

deepset_mcp.tools.deploy_index async

deploy_index(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    index_name: str,
) -> str | PipelineValidationResult

Deploys an index to production.

This function attempts to deploy the specified index in the given workspace. If the deployment fails due to validation errors, it returns an object describing the validation errors.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
index_name	str	Name of the index to deploy.	required

Returns:

Type	Description
str | PipelineValidationResult	A string indicating the deployment result or the validation results including errors.

deepset_mcp.tools.get_index async

get_index(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    index_name: str,
) -> Index | str

Fetches detailed configuration information for a specific index, identified by its unique index_name.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	Deepset API client to use for requesting the index.	required
workspace	str	Workspace of which to get the index from.	required
index_name	str	Unique name of the index to fetch.	required

Returns:

Type	Description
Index | str	The index configuration or an error message.

deepset_mcp.tools.list_indexes async

list_indexes(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    after: str | None = None,
) -> PaginatedResponse[Index] | str

Retrieves a list of all indexes available within the currently configured deepset workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
after	str | None	The cursor to fetch the next page of results. If there are more results to fetch, the cursor will appear as next_cursor on the response.	None

Returns:

Type	Description
PaginatedResponse[Index] | str	List of indexes or error message.

deepset_mcp.tools.update_index async

update_index(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    index_name: str,
    original_config_snippet: str,
    replacement_config_snippet: str,
    skip_validation_errors: bool = True,
) -> Index | IndexOperationWithErrors | str

Updates an index configuration in the specified workspace with a replacement configuration snippet.

This function validates the replacement configuration snippet before applying it to the index. If the validation fails and skip_validation_errors is False, it returns error messages. Otherwise, the replacement snippet is used to update the index's configuration.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
index_name	str	Name of the index to update.	required
original_config_snippet	str	The configuration snippet to replace.	required
replacement_config_snippet	str	The new configuration snippet.	required
skip_validation_errors	bool	If True (default), updates the index even if validation fails. If False, stops update when validation fails.	True

Returns:

Type	Description
Index | IndexOperationWithErrors | str	Updated index or error message.

deepset_mcp.tools.validate_index async

validate_index(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    yaml_configuration: str,
) -> IndexValidationResultWithYaml | str

Validates the provided index YAML configuration against the deepset API.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
yaml_configuration	str	The YAML configuration to validate.	required

Returns:

Type	Description
IndexValidationResultWithYaml | str	Validation result with original YAML or error message.

deepset_mcp.tools.get_models async

get_models(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    limit: int = 100,
    page_number: int = 1,
    connected: bool | None = None,
    provider: ModelProvider | str | None = None,
    model: str | None = None,
) -> ModelList | str

Lists the models including their configuration options available for use in a workspace's pipelines and indexes.

This includes predefined models offered by deepset as well as custom models configured at the workspace or organization level. Use this tool to discover which model names and providers can be used, which configuration options are available, and which default configuration is offered when configuring chat generators.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
limit	int	Maximum number of models to return per page.	100
page_number	int	The page to fetch, starting at 1.	1
connected	bool | None	If set, only return models for which the workspace does (True) or does not (False) have a working integration configured.	None
provider	ModelProvider | str | None	If set, only return models from this provider. Accepts a well-known ModelProvider value (e.g. 'openai', 'anthropic', 'gemini', 'aws-bedrock') or any other provider name as a plain string. Case-insensitive, exact match.	None
model	str | None	If set, only return models whose configured model name contains this value (e.g. 'gpt-4o'). Case-insensitive, substring match.	None

Returns:

Type	Description
ModelList | str	A page of models including their configuration options or an error message.

deepset_mcp.tools.create_get_from_object_store

create_get_from_object_store(
    explorer: RichExplorer,
) -> Callable[..., Any]

Creates the get_from_object_store tool.

deepset_mcp.tools.create_get_slice_from_object_store

create_get_slice_from_object_store(
    explorer: RichExplorer,
) -> Callable[..., Any]

Creates the get_slice_from_object_store tool.

deepset_mcp.tools.create_grep_object_store

create_grep_object_store(
    explorer: RichExplorer,
) -> Callable[..., Any]

Creates the grep_object_store tool.

deepset_mcp.tools.create_sed_object_store

create_sed_object_store(
    explorer: RichExplorer,
) -> Callable[..., Any]

Creates the sed_object_store tool.

deepset_mcp.tools.create_yq_object_store

create_yq_object_store(
    explorer: RichExplorer,
) -> Callable[..., Any]

Creates the yq_object_store tool.

deepset_mcp.tools.create_pipeline async

create_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    yaml_configuration: str,
    skip_validation_errors: bool = True,
) -> DeepsetPipeline | PipelineOperationWithErrors | str

Creates a new pipeline within the currently configured deepset workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to create.	required
yaml_configuration	str	YAML configuration for the pipeline.	required
skip_validation_errors	bool	If True (default), creates the pipeline even if validation fails. If False, stops creation when validation fails.	True

Returns:

Type	Description
DeepsetPipeline | PipelineOperationWithErrors | str	Created pipeline or error message.

deepset_mcp.tools.create_pipeline_version async

create_pipeline_version(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    yaml_configuration: str,
    description: str | None = None,
    is_draft: bool = False,
) -> PipelineVersion | str

Creates a new version of an existing pipeline with the provided YAML configuration.

Use this to update a pipeline's configuration. Each call creates a new immutable version, preserving the full history of changes.

If is_draft is True, and there is already a draft version, the existing draft will be finalized and incremented to a new version number.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to create a version for.	required
yaml_configuration	str	The new YAML configuration for this version.	required
description	str | None	Optional description of what changed in this version.	None
is_draft	bool	If True, the version is created as a draft (default: False).	False

Returns:

Type	Description
PipelineVersion | str	The newly created pipeline version or error message.

deepset_mcp.tools.debug_pipeline async

debug_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    yaml_configuration: str,
    inputs: dict[str, Any] | None = None,
    break_at_component_name: str | None = None,
    break_at_visit_count: int = 0,
    resume_from: dict[str, Any] | None = None,
    files: list[str] | None = None,
    pipeline_id: str | None = None,
    pipeline_version_id: str | None = None,
    dry_run: bool = False,
) -> PipelineDebugResult | str

Runs a pipeline configuration in debug mode: pin a breakpoint, resume a snapshot, or trace a full run.

Debugs a pipeline configuration directly (not a saved pipeline by name) -- pass the YAML you want to test, e.g. from get_pipeline_version, create_pipeline_version, or a local draft. The inline run trace is always returned, so a failure is visible even for a run that never reaches a breakpoint.

One call carries at most one of:

• break_at_component_name (with break_at_visit_count) -- run from inputs until the breakpoint is hit, then stop and return a resumable snapshot in the 'snapshot' field. Pass that back as resume_from to continue the run.
• resume_from -- replay a snapshot returned by a previous debug run to completion; inputs are ignored, they come from the snapshot.
• neither -- run the pipeline from inputs to completion as a plain debug run.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
yaml_configuration	str	The pipeline YAML configuration to debug.	required
inputs	dict[str, Any] | None	Named pipeline inputs keyed by the input name declared under the pipeline config's 'inputs' mapping (e.g. {"query": "What is love?"}). Ignored when resume_from is set.	None
break_at_component_name	str | None	Name of the component to break at. Mutually exclusive with resume_from; omit both to run to completion as a plain debug run.	None
break_at_visit_count	int	Break when the target has been visited this many times (0 breaks before the first visit; relevant for loops/cycles). Only used if break_at_component_name is set.	0
resume_from	dict[str, Any] | None	A snapshot returned by a previous debug run (its 'snapshot' field), replayed to completion. Mutually exclusive with break_at_component_name.	None
files	list[str] | None	File IDs to download and inject into the inputs declared under the pipeline config's 'inputs.files' mapping.	None
pipeline_id	str | None	Optional ID of the pipeline this debug run is associated with.	None
pipeline_version_id	str | None	Optional ID of the pipeline version to associate the run with (requires pipeline_id).	None
dry_run	bool	Best-effort stateless run: state-modifying components (e.g. DocumentWriter) are replaced with no-op equivalents so the pipeline can be inspected without side effects. Required for indexing pipelines (their document store carries no index until deploy time); harmless for query pipelines. Set it on resume too if the original run used dry_run, otherwise the run is rejected.	False

Returns:

Type	Description
PipelineDebugResult | str	PipelineDebugResult with status, result/snapshot, and the run trace, or an error message.

deepset_mcp.tools.deploy_pipeline async

deploy_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    version_id: str | None = None,
    wait_for_deployment: bool = False,
    timeout_seconds: float = 600,
    poll_interval: float = 10,
) -> PipelineValidationResult | str

Deploys a pipeline to production.

This function attempts to deploy the specified pipeline in the given workspace. If the deployment fails due to validation errors, it returns a validation result.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to deploy.	required
version_id	str | None	Optional ID of the pipeline version to deploy. If None, deploys the latest non-draft version.	None
wait_for_deployment	bool	If True, waits for the pipeline to reach DEPLOYED status.	False
timeout_seconds	float	Maximum time to wait for deployment when wait_for_deployment is True (default: 600.0).	600
poll_interval	float	Time between status checks in seconds when wait_for_deployment is True (default: 10.0).	10

Returns:

Type	Description
PipelineValidationResult | str	Deployment validation result or error message.

deepset_mcp.tools.get_pipeline async

get_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
) -> DeepsetPipeline | str

Fetches information for a specific pipeline, identified by its unique pipeline_name.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	The name of the pipeline to fetch.	required

Returns:

Type	Description
DeepsetPipeline | str	Pipeline details or error message.

deepset_mcp.tools.get_pipeline_logs async

get_pipeline_logs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    limit: int = 30,
    level: LogLevel | None = None,
    after: str | None = None,
) -> PaginatedResponse[PipelineLog] | str

Fetches logs for a specific pipeline.

Retrieves log entries for the specified pipeline, with optional filtering by log level. This is useful for debugging pipeline issues or monitoring pipeline execution.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to fetch logs for.	required
limit	int	Maximum number of log entries to return (default: 30).	30
level	LogLevel | None	Filter logs by level. If None, returns all levels.	None
after	str | None	The cursor to fetch the next page of results.	None

Returns:

Type	Description
PaginatedResponse[PipelineLog] | str	Pipeline logs or error message.

deepset_mcp.tools.get_pipeline_version async

get_pipeline_version(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    version_id: str,
) -> PipelineVersion | str

Fetches a specific version of a pipeline by its version ID.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline.	required
version_id	str	UUID of the version to fetch.	required

Returns:

Type	Description
PipelineVersion | str	Pipeline version details or error message.

deepset_mcp.tools.list_pipeline_versions async

list_pipeline_versions(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    after: str | None = None,
) -> PaginatedResponse[PipelineVersion] | str

Lists all versions of a pipeline, ordered by version number descending (newest first).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to list versions for.	required
after	str | None	Cursor (version_id UUID) to fetch the next page of results.	None

Returns:

Type	Description
PaginatedResponse[PipelineVersion] | str	Paginated list of pipeline versions or error message.

deepset_mcp.tools.list_pipelines async

list_pipelines(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    after: str | None = None,
) -> PaginatedResponse[DeepsetPipeline] | str

Retrieves a list of all pipeline available within the currently configured deepset workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
after	str | None	The cursor to fetch the next page of results. If there are more results to fetch, the cursor will appear as next_cursor on the response.	None

Returns:

Type	Description
PaginatedResponse[DeepsetPipeline] | str	List of pipelines or error message.

deepset_mcp.tools.patch_pipeline_version async

patch_pipeline_version(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    version_id: str,
    yaml_configuration: str | None = None,
    description: str | None = None,
    is_draft: bool | None = None,
) -> PipelineVersion | str

Updates fields of an existing pipeline version in place.

At least one of yaml_configuration, description, or is_draft must be provided.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline.	required
version_id	str	UUID of the version to update.	required
yaml_configuration	str | None	New YAML configuration for the version (optional).	None
description	str | None	New description for the version (optional).	None
is_draft	bool | None	New draft status for the version (optional).	None

Returns:

Type	Description
PipelineVersion | str	The updated pipeline version or error message.

deepset_mcp.tools.restore_pipeline_version async

restore_pipeline_version(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    version_id: str,
) -> PipelineVersion | str

Restores a non-draft pipeline version to be editable as a new draft.

The previous draft (if any) is finalized, getting an incremented version number.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to restore.	required
version_id	str	UUID of the version to restore.	required

Returns:

Type	Description
PipelineVersion | str	The restored pipeline version or error message.

deepset_mcp.tools.search_pipeline async

search_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query: str,
) -> DeepsetSearchResponse | str

Searches using a pipeline.

Uses the specified pipeline to perform a search with the given query. Before executing the search, checks if the pipeline is deployed (status = DEPLOYED). Returns search results.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to use for search.	required
query	str	The search query to execute.	required

Returns:

Type	Description
DeepsetSearchResponse | str	Search results or error message.

deepset_mcp.tools.search_pipeline_with_filters async

search_pipeline_with_filters(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query: str,
    filters: dict[str, Any] | None = None,
) -> DeepsetSearchResponse | str

Searches using a pipeline with filters.

Uses the specified pipeline to perform a search with the given query and filters. Filters follow the Haystack filter syntax: https://docs.haystack.deepset.ai/docs/metadata-filtering. Before executing the search, checks if the pipeline is deployed (status = DEPLOYED). Returns search results.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to use for search.	required
query	str	The search query to execute.	required
filters	dict[str, Any] | None	The filters to apply to the search.	None

Returns:

Type	Description
DeepsetSearchResponse | str	Search results or error message.

deepset_mcp.tools.search_pipeline_with_params async

search_pipeline_with_params(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query: str,
    params: dict[str, Any] | None = None,
) -> DeepsetSearchResponse | str

Searches using a pipeline with params.

Uses the specified pipeline to perform a search with the given query and params. Params can be arbitrary parameters to customize the search behavior. Filters can be used as well under the "filters" key in params. Filters follow the Haystack filter syntax: https://docs.haystack.deepset.ai/docs/metadata-filtering. Before executing the search, checks if the pipeline is deployed (status = DEPLOYED). Returns search results.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to use for search.	required
query	str	The search query to execute.	required
params	dict[str, Any] | None	The parameters to customize the search.	None

Returns:

Type	Description
DeepsetSearchResponse | str	Search results or error message.

deepset_mcp.tools.validate_pipeline async

validate_pipeline(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    yaml_configuration: str,
) -> PipelineValidationResultWithYaml | str

Validates the provided pipeline YAML configuration against the deepset API.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
yaml_configuration	str	The YAML configuration to validate.	required

Returns:

Type	Description
PipelineValidationResultWithYaml | str	Validation result with original YAML or error message.

deepset_mcp.tools.get_template async

get_template(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    template_name: str,
) -> PipelineTemplate | str

Fetches detailed information for a specific pipeline or indexing template, identified by its template_name.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API requests.	required
workspace	str	The workspace to fetch template from.	required
template_name	str	The name of the template to fetch.	required

Returns:

Type	Description
PipelineTemplate | str	Pipeline or indexing template details or error message.

deepset_mcp.tools.list_templates async

list_templates(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    limit: int = 100,
    pipeline_type: PipelineType | str | None = None,
    after: str | None = None,
) -> PaginatedResponse[PipelineTemplate] | str

Retrieves a list of all available pipeline and indexing templates.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API requests.	required
workspace	str	The workspace to list templates from.	required
limit	int	Maximum number of templates to return (default: 100).	100
pipeline_type	PipelineType | str | None	The type of pipeline to return.	None
after	str | None	The cursor to fetch the next page of results. If there are more results to fetch, the cursor will appear as next_cursor on the response.	None

Returns:

Type	Description
PaginatedResponse[PipelineTemplate] | str	List of pipeline templates or error message.

deepset_mcp.tools.search_templates async

search_templates(
    *,
    client: AsyncClientProtocol,
    query: str,
    model: ModelProtocol,
    workspace: str,
    top_k: int = 10,
    pipeline_type: PipelineType | str = QUERY,
) -> PipelineTemplateSearchResults | str

Searches for pipeline or indexing templates based on name or description using semantic similarity.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The API client to use.	required
query	str	The search query.	required
model	ModelProtocol	The model to use for computing embeddings.	required
workspace	str	The workspace to search templates from.	required
top_k	int	Maximum number of results to return (default: 10).	10
pipeline_type	PipelineType | str	The type of pipeline to return ('indexing' or 'query'; default: 'query').	QUERY

Returns:

Type	Description
PipelineTemplateSearchResults | str	Search results with similarity scores or error message.

deepset_mcp.tools.get_pipeline_trace async

get_pipeline_trace(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query_id: str,
) -> PipelineTraceEntry | str

Retrieves the Haystack pipeline run trace including all spans for a single search history record.

Returns the execution trace for one query: every component span with essential tags (excluding the component's input and output), timing, and failure details. Use this to deep-dive into a specific query run identified by its query_id (obtainable from list_pipeline_traces or list_pipeline_search_history).

For a targeted look at one span including the input and output at one component, use get_pipeline_trace_span_tags; for the logs, use get_pipeline_trace_logs.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline.	required
query_id	str	UUID of the search history query whose trace to retrieve. Obtain this from the query_id / search_history_id field of a list_pipeline_traces or list_pipeline_search_history response.	required

Returns:

Type	Description
PipelineTraceEntry | str	The pipeline trace entry including all spans or an error message.

deepset_mcp.tools.get_pipeline_trace_logs async

get_pipeline_trace_logs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query_id: str,
) -> list[HaystackTraceLog] | str

Retrieves the log entries for a single Haystack pipeline run trace.

Returns the run's logs (e.g. to diagnose warnings or errors emitted during the run). Each entry includes the logger, level, message, timestamp, and extra fields.

Obtain query_id from list_pipeline_traces or list_pipeline_search_history.

If errors occur outside of the pipeline (e.g. in the API or search history service), they will not appear in the trace logs. Use the get_pipeline_logs tool to retrieve logs for the pipeline itself (e.g. startup errors, configuration issues, orother runtime problems).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline.	required
query_id	str	UUID of the search history query.	required

Returns:

Type	Description
list[HaystackTraceLog] | str	List of log entries or an error message.

deepset_mcp.tools.get_pipeline_trace_span_tags async

get_pipeline_trace_span_tags(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query_id: str,
    span_id: str,
) -> dict[str, Any] | str

Retrieves all tags for a single span within a Haystack pipeline run trace.

A span's tags carry the component-level detail, including its input and output (e.g. haystack.component.input / haystack.component.output) plus type and error information. Use this to inspect one component run in detail.

Obtain span_id from a span in a get_pipeline_trace response, and query_id from list_pipeline_traces or list_pipeline_search_history.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline.	required
query_id	str	UUID of the search history query.	required
span_id	str	UUID of the span whose tags to retrieve.	required

Returns:

Type	Description
dict[str, Any] | str	The span's tag dictionary or an error message.

deepset_mcp.tools.list_pipeline_search_history async

list_pipeline_search_history(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    limit: int = 10,
    after: str | None = None,
    query_filter: str | None = None,
    sort_field: Literal[
        "created_at", "query", "duration", "feedbacks/score"
    ] = "created_at",
    sort_order: Literal["ASC", "DESC"] = "DESC",
) -> PaginatedResponse[SearchHistoryEntry] | str

Retrieves search history for a specific pipeline with pagination.

Returns past searches run with the given pipeline. Each entry includes the search query (request.query), results (response), timing (time/duration), status, user info, feedback, labels, and note.

Search history is archived ~30 minutes after a search runs and is then available via this endpoint.

Use the after parameter with next_cursor from the response to fetch the next page.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to get search history for.	required
limit	int	Maximum number of entries to return per page (default 10, max 1000).	10
after	str | None	ISO-8601 timestamp cursor to fetch entries older than this point. Pass the value from next_cursor on the previous response.	None
query_filter	str | None	An OData filter expression to narrow down results. Supported fields: query, client_source_path, pipeline_version_id, answer, api_key, created_at, created_by, tags/tag_id, feedbacks, feedbacks/score, feedbacks/comment, feedbacks/bookmarked, session_id, search_session_id, feedbacks/result_id, request/filters, request/params, duration, labels, status, note. Example: "created_at ge 2024-01-01T00:00:00Z" or "status eq 'failed'".	None
sort_field	Literal['created_at', 'query', 'duration', 'feedbacks/score']	Field to sort results by. One of: created_at, query, duration, feedbacks/score. Defaults to created_at.	'created_at'
sort_order	Literal['ASC', 'DESC']	Sort direction — ASC (oldest first) or DESC (newest first). Defaults to DESC.	'DESC'

Returns:

Type	Description
PaginatedResponse[SearchHistoryEntry] | str	Paginated list of search history entries or error message.

deepset_mcp.tools.list_pipeline_traces async

list_pipeline_traces(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    limit: int = 10,
    after: str | None = None,
    query_filter: str | None = None,
    sort_field: Literal[
        "created_at", "query", "duration", "feedbacks/score"
    ] = "created_at",
    sort_order: Literal["ASC", "DESC"] = "DESC",
) -> PaginatedResponse[PipelineTraceSummary] | str

Lists Haystack pipeline run trace summaries for a specific pipeline.

Returns one lightweight summary per query run — query_id, query text, status, timing (duration_s, created_at), and failure details if the run failed. Summaries do not include spans or logs. Use this to browse runs, find slow or failed queries, then pass a query_id to get_pipeline_trace for the full execution trace (spans with essential tags such as component type), get_pipeline_trace_span_tags for a single span with full tags (including input/output), or get_pipeline_trace_logs for the logs of the trace.

Use the after parameter with next_cursor from the response to fetch the next page.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str	Name of the pipeline to retrieve traces for.	required
limit	int	Maximum number of trace entries to return per page (default 10).	10
after	str | None	ISO-8601 timestamp cursor from next_cursor on the previous response.	None
query_filter	str | None	An OData filter expression to narrow down results. Supported fields: query, client_source_path, pipeline_version_id, answer, api_key, created_at, created_by, tags/tag_id, feedbacks, feedbacks/score, feedbacks/comment, feedbacks/bookmarked, session_id, search_session_id, feedbacks/result_id, request/filters, request/params, duration, labels, status, note. Example: "status eq 'failed'" or "created_at ge 2024-01-01T00:00:00Z".	None
sort_field	Literal['created_at', 'query', 'duration', 'feedbacks/score']	Field to sort results by. One of: created_at, query, duration, feedbacks/score. Defaults to created_at.	'created_at'
sort_order	Literal['ASC', 'DESC']	Sort direction — ASC (oldest first) or DESC (newest first). Defaults to DESC.	'DESC'

Returns:

Type	Description
PaginatedResponse[PipelineTraceSummary] | str	Paginated list of pipeline trace summaries or an error message.

deepset_mcp.tools.list_search_history async

list_search_history(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    limit: int = 10,
    after: str | None = None,
    query_filter: str | None = None,
    sort_field: Literal[
        "created_at", "query", "duration", "feedbacks/score"
    ] = "created_at",
    sort_order: Literal["ASC", "DESC"] = "DESC",
) -> PaginatedResponse[SearchHistoryEntry] | str

Retrieves search history for the configured deepset workspace.

Returns past searches run in the workspace, including queries, answers, prompts, feedback, and metadata. Use this to inspect what users have searched for, analyze usage, or debug pipeline behavior.

Each entry includes: - request.query — the search query text - time / created_at — when the search ran - duration — how long it took (seconds) - status — 'success' or 'failed' - pipeline.name — which pipeline handled the query - response — the list of search results - feedback, labels, note — user annotations

Use the after parameter with the next_cursor value from the previous response to fetch the next page.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
limit	int	Maximum number of entries to return per page (default 10, max 1000).	10
after	str | None	ISO-8601 timestamp cursor to fetch entries older than this point. Pass the value from next_cursor on the previous response.	None
query_filter	str | None	An OData filter expression to narrow down results. Supported fields: query, client_source_path, pipeline_version_id, answer, api_key, created_at, created_by, tags/tag_id, feedbacks, feedbacks/score, feedbacks/comment, feedbacks/bookmarked, session_id, search_session_id, feedbacks/result_id, request/filters, request/params, duration, labels, status, note. Example: "created_at ge 2024-01-01T00:00:00Z" or "query eq 'my search'".	None
sort_field	Literal['created_at', 'query', 'duration', 'feedbacks/score']	Field to sort results by. One of: created_at, query, duration, feedbacks/score. Defaults to created_at.	'created_at'
sort_order	Literal['ASC', 'DESC']	Sort direction — ASC (oldest first) or DESC (newest first). Defaults to DESC.	'DESC'

Returns:

Type	Description
PaginatedResponse[SearchHistoryEntry] | str	Paginated list of search history entries or error message.

deepset_mcp.tools.get_secret async

get_secret(
    *, client: AsyncClientProtocol, secret_id: str
) -> EnvironmentSecret | str

Retrieves detailed information about a specific secret by its ID.

Use this tool to get information about a specific secret when you know its ID. The secret value itself is not returned for security reasons, only metadata.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The deepset API client	required
secret_id	str	The unique identifier of the secret to retrieve	required

Returns:

Type	Description
EnvironmentSecret | str	Secret information or error message

deepset_mcp.tools.list_secrets async

list_secrets(
    *,
    client: AsyncClientProtocol,
    limit: int = 10,
    after: str | None = None,
) -> EnvironmentSecretList | str

Lists all secrets available in the user's deepset organization.

Use this tool to retrieve a list of secrets with their names and IDs. This is useful for getting an overview of all secrets before retrieving specific ones.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The deepset API client	required
limit	int	Maximum number of secrets to return (default: 10)	10
after	str | None	The cursor to fetch the next page of results	None

Returns:

Type	Description
EnvironmentSecretList | str	List of secrets or error message

deepset_mcp.tools.load_skill async

load_skill(skill_name: str) -> str

Loads the full content of a bundled skill guide by name.

This docstring is replaced at import time with a dynamically generated version that lists every skill currently bundled with the server (see _build_docstring).

Parameters:

Name	Type	Description	Default
skill_name	str	The name of the skill to load.	required

Returns:

Type	Description
str	The skill's markdown content, or an error message if not found.

deepset_mcp.tools.create_workspace async

create_workspace(
    *, client: AsyncClientProtocol, name: str
) -> NoContentResponse | str

Creates a new workspace with the specified name.

This tool creates a new workspace that can be used to organize pipelines, indexes, and other resources. The workspace name must be unique across the platform. Once created, you can start deploying pipelines and other resources within this workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
name	str	The name for the new workspace. Must be unique.	required

Returns:

Type	Description
NoContentResponse | str	Success confirmation or error message.

deepset_mcp.tools.get_workspace async

get_workspace(
    *, client: AsyncClientProtocol, workspace_name: str
) -> Workspace | str

Fetches detailed information for a specific workspace by name.

This tool retrieves comprehensive details about a specific workspace, including its unique ID, supported languages, and configuration settings. Use this when you need detailed information about a particular workspace.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace_name	str	The name of the workspace to fetch details for.	required

Returns:

Type	Description
Workspace | str	Workspace details or error message.

deepset_mcp.tools.list_workspaces async

list_workspaces(
    *, client: AsyncClientProtocol
) -> list[Workspace] | str

Retrieves a list of all workspaces available to the user.

This tool provides an overview of all workspaces that the user has access to. Each workspace contains information about its name, ID, supported languages, and default idle timeout settings.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required

Returns:

Type	Description
list[Workspace] | str	List of workspaces or error message.