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	Replace an existing index's configuration with a full, updated YAML.
validate_index	required	explorable, referenceable	Validate an index configuration without saving it.
deploy_index	required	explorable	Deploy an index.

Deployments (AI Gateways)

A deployment serves a pipeline behind a stable endpoint, independent of the pipeline's own draft/version history. Each deployment tracks its own history of served pipeline configurations as revisions.

MCP tool name	Workspace	Memory	Description
list_deployments	required	explorable	List all deployments in the workspace.
get_deployment	required	explorable	Fetch a deployment's details, active revision, and runtime status.
create_deployment	required	explorable, referenceable	Create a new deployment, optionally linked to a pipeline.
update_deployment	required	explorable, referenceable	Update a deployment's metadata, sizing, or execution mode.
delete_deployment	required	explorable	Delete a deployment along with all of its revisions.
list_deployment_tags	required	explorable	List distinct tags in use across deployments in the workspace.
add_deployment_tag	required	explorable	Add a tag to a deployment.
delete_deployment_tag	required	explorable	Remove a tag from a deployment.
list_deployment_revisions	required	explorable	List a deployment's revision history.
get_deployment_revision	required	explorable	Fetch a specific revision, including its config YAML.
create_deployment_revision	required	explorable, referenceable	Push a new revision onto a deployment.
activate_deployment_revision	required	explorable	Activate a revision as the deployment's served revision.
activate_deployment	required	explorable	Re-activate a deployment's current active revision.
deactivate_deployment	required	explorable	Mark a deployment as no longer desired to be served.
list_deployment_activity	required	explorable	List activation and revision activity for a deployment.
get_deployment_metrics	required	explorable	Fetch per-replica CPU/memory usage and replica counts.
get_deployment_stats	required	explorable	Fetch query volume, outcome split, and run durations.

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.

Evaluation

MCP tool name	Workspace	Memory	Description
list_evaluators	required	explorable	List the workspace's Evaluators with the Metrics each declares, optionally only archived or only active ones.
get_evaluator	required	explorable	Fetch one Evaluator with its versions, or one version with its Python source.
list_metric_groups	required	explorable	List the workspace's Metric Groups, optionally with each one's most recent scoring run on a pipeline.
list_experiments	required	explorable	List the workspace's Experiments (a candidate version against a baseline on a Dataset), optionally only those on one pipeline.
create_experiment	required	none	Create an Experiment: a candidate pipeline version against a Recorded or Pipeline-version baseline on a Dataset (preview first: it costs money).
get_experiment	required	explorable	Read one Experiment: test cases, each side's replays, scoring counts and error.
update_experiment	required	none	Rename an Experiment or change a side (replays and judges again; preview first).
rerun_failed_experiment	required	none	Judge again the failed evaluations, or replay again the failed replays (costs money).
rescore_experiment	required	none	Score both sides again with the Metric Group as it is now (bills every evaluation again).
delete_experiment	required	none	Delete an Experiment (destructive); its Sessions and scoring runs are kept.
get_experiment_results	required	explorable	Read an Experiment's results: each Metric and duration, tokens and cost, candidate against baseline, then per test case.
get_experiment_run	required	explorable	Read one scoring run: cell counts, a summary per Metric, the whole-run aggregate, usage and cost, and the grid rows, optionally filtered by origin, Service, version or Session.
list_experiment_runs	required	explorable	List a Metric Group's scoring runs on a pipeline, or every run that judged one Session.
start_experiment_run	required	none	Score named Sessions or a time window with a Metric Group, outside an Experiment (preview a window first: judged Evaluators cost money).
run_evaluator	required	none	Run one saved Evaluator version on one Session and keep the Evaluation Run (judged Evaluators cost money).
list_evaluation_runs	required	explorable	List a pipeline's Evaluation Runs, newest first.
get_evaluation_run	required	explorable	Read one Evaluation Run: its progress, or its Metrics.
list_sessions	required	explorable	List the Sessions of a pipeline that a scoring run can judge.
try_evaluator	required	none	Try Evaluator source on one Session and return its Metrics; persists nothing.
get_evaluation_try	required	none	Read a try that was still running.
replay_session	required	none	Experiment support: replay one Session on a pipeline version into a new Session, to reproduce or retry one test case's replay (costs money; not added to the Experiment; to retry an Experiment's failed replays use rerun_failed_experiment).
get_session_replay	required	none	Experiment support: read one replay run to see why it failed (status, error detail, setup and cleanup logs, the new Session).
list_datasets	required	explorable	List the workspace's Datasets (named lists of test cases), optionally only those on one pipeline.
get_dataset	required	explorable	Fetch one Dataset with all its test cases.
create_dataset	required	none	Create a Dataset, optionally with its first test cases (recorded Sessions or inputs).
update_dataset	required	none	Rename a Dataset.
delete_dataset	required	none	Delete a Dataset and its test cases (destructive).
add_test_cases	required	none	Add test cases to a Dataset.
update_test_case	required	none	Change one test case's name, inputs, expected data or scripts.
copy_test_cases	required	none	Copy test cases from any Dataset of the workspace into a Dataset.
remove_test_cases	required	none	Remove test cases from a Dataset (destructive).
create_evaluator	required	none	Create an Evaluator from Python source, optionally adding it to Metric Groups; try the code with try_evaluator first.
update_evaluator	required	none	Rename an Evaluator or save new source as a new version.
set_evaluator_archived	required	none	Archive or unarchive an Evaluator; nothing is deleted.
list_evaluator_templates	required	explorable	List the built-in Evaluator templates with their code and Metrics.
create_metric_group	required	none	Create a Metric Group of Evaluators, optionally with Metric weights for the Composite.
update_metric_group	required	none	Replace a Metric Group's name and Evaluators, and optionally its Metric weights.
delete_metric_group	required	none	Delete a Metric Group and its scoring runs (destructive).

Cost

MCP tool name	Workspace	Memory	Description
get_cost_totals	optional	explorable	Read the LLM cost, tokens and requests of a workspace or pipeline over a date range, or of the whole organization when no workspace is given (organization admins).
get_cost_over_time	optional	explorable	Read the LLM cost of a workspace or pipeline per UTC day, or of the whole organization when no workspace is given (organization admins).
get_cost_breakdown	optional	explorable	Read the LLM cost grouped by model, workspace, pipeline, deployment, API key or provider, for a workspace or (organization admins, no workspace given) the whole organization.

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_organizations	not needed	no_memory	List the organizations the user belongs to (OAuth only).
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	optional	explorable	List the secrets available to the organization, or to a workspace if one is given.
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 using the same pipeline as the documentation MCP server.
list_doc_sections	not needed	none	List the main documentation sections with descriptions and URLs.
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_cost_breakdown async

get_cost_breakdown(
    *,
    client: AsyncClientProtocol,
    workspace: str | None = None,
    group_by: CostGroupBy,
    pipeline_name: str | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    sort_by: CostSortBy | None = None,
    sort_order: Literal["ASC", "DESC"] | None = None,
    limit: int = 10,
    page_number: int = 1,
    services: list[str] | None = None,
    providers: list[str] | None = None,
    api_keys: list[str] | None = None,
) -> CostBreakdown | str

Reads the LLM cost of the workspace, or of one pipeline, grouped by model, pipeline, Service or API key.

Use this to find what drove the cost: which models, pipelines, Services or API keys spent the most. Costs are in USD. Results are sorted by cost, highest first, unless you set sort_by and sort_order. Each entry has a key (a model or provider name, or a UUID for the other dimensions) and a readable label. A deleted pipeline still shows up with group_by='pipeline', labelled with its UUID. total is the number of groups across all pages; when has_more is true, read the next page_number. total_requests counts queries, not individual LLM calls. A cost_total of null means the group had usage but none of it was priced. Without dates the range is the last 30 days.

A Service (group_by='deployment') is a published Service endpoint; a deployed pipeline is a pipeline (group_by='pipeline'). The two overlap: a query through a Service that runs a pipeline counts in both, so never add Service groups and pipeline groups together. Usage that did not go through a Service shows up as __unattributed__ under group_by='deployment'.

Without workspace the figures cover the whole organization, as the Cost Management page does for an organization admin; this needs the organization admin role. Use workspace for one workspace. In that organization view pipeline_name and Service names can't be used (they belong to a workspace); pass Service ids instead.

Narrow the breakdown with services, providers and api_keys, for example the models of one Service. They combine: usage must match every kind you set, and any one value within a list.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str | None	The workspace name. Omit for the whole organization, which needs the organization admin role; then pipeline_name and Service names can't be used, only Service ids.	None
group_by	CostGroupBy	The dimension to group by: model, workspace, pipeline, deployment (a Service), api_key or provider.	required
pipeline_name	str | None	Restrict to this pipeline. Omit for the whole workspace. Needs Pipelines read as well as Costs read.	None
start_date	str | None	Inclusive start as an ISO timestamp. Defaults to 30 days before end_date.	None
end_date	str | None	Exclusive end as an ISO timestamp. Defaults to no upper bound.	None
sort_by	CostSortBy | None	Sort by label, cost_total, total_tokens or total_requests. Defaults to cost_total.	None
sort_order	Literal['ASC', 'DESC'] | None	ASC or DESC. Defaults to DESC.	None
limit	int	Groups per page, from 1 to 100.	10
page_number	int	The page to read, starting at 1.	1
services	list[str] | None	Restrict to these Services (deployment in the API; a published Service endpoint, not a deployed pipeline, which is a pipeline). Each value is a Service name or its id, the key from get_cost_breakdown with group_by='deployment'. Looking a Service up by name needs Services read as well as Costs read; an id needs only Costs read.	None
providers	list[str] | None	Restrict to these providers. Use the provider ids from get_cost_breakdown with group_by='provider', such as bedrock_converse or openai, not their display names.	None
api_keys	list[str] | None	Restrict to these API keys. Use the key ids from get_cost_breakdown with group_by='api_key', never a key's secret token.	None

Returns:

Type	Description
CostBreakdown | str	One page of the breakdown, or an error message.

deepset_mcp.tools.get_cost_over_time async

get_cost_over_time(
    *,
    client: AsyncClientProtocol,
    workspace: str | None = None,
    pipeline_name: str | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    services: list[str] | None = None,
    providers: list[str] | None = None,
    api_keys: list[str] | None = None,
) -> CostOverTime | str

Reads the LLM cost of the workspace, or of one pipeline, per UTC day.

Use this to see how spending developed, find the day a cost spike started, or compare periods. Costs are in USD. There is one point per day with usage; days without usage are left out, so a missing day means zero cost. A cost_total of null means that day had usage but none of it was priced. Without dates the range is the last 30 days. start_date is inclusive and end_date exclusive. The daily figures leave out unpriced LLM calls; use get_cost_totals to check whether the cost is complete.

Without workspace the figures cover the whole organization, as the Cost Management page does for an organization admin; this needs the organization admin role. Use workspace for one workspace. In that organization view pipeline_name and Service names can't be used (they belong to a workspace); pass Service ids instead.

Narrow the figures with services, providers and api_keys. They combine: usage must match every kind you set, and any one value within a list.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str | None	The workspace name. Omit for the whole organization, which needs the organization admin role; then pipeline_name and Service names can't be used, only Service ids.	None
pipeline_name	str | None	Restrict to this pipeline. Omit for the whole workspace. Needs Pipelines read as well as Costs read.	None
start_date	str | None	Inclusive start as an ISO timestamp. Defaults to 30 days before end_date.	None
end_date	str | None	Exclusive end as an ISO timestamp. Defaults to no upper bound.	None
services	list[str] | None	Restrict to these Services (deployment in the API; a published Service endpoint, not a deployed pipeline, which is a pipeline). Each value is a Service name or its id, the key from get_cost_breakdown with group_by='deployment'. Looking a Service up by name needs Services read as well as Costs read; an id needs only Costs read.	None
providers	list[str] | None	Restrict to these providers. Use the provider ids from get_cost_breakdown with group_by='provider', such as bedrock_converse or openai, not their display names.	None
api_keys	list[str] | None	Restrict to these API keys. Use the key ids from get_cost_breakdown with group_by='api_key', never a key's secret token.	None

Returns:

Type	Description
CostOverTime | str	The daily cost, or an error message.

deepset_mcp.tools.get_cost_totals async

get_cost_totals(
    *,
    client: AsyncClientProtocol,
    workspace: str | None = None,
    pipeline_name: str | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    services: list[str] | None = None,
    providers: list[str] | None = None,
    api_keys: list[str] | None = None,
) -> CostTotals | str

Reads the total LLM cost, tokens and requests of the workspace, or of one pipeline, over a date range.

Use this to answer how much a workspace or pipeline spent on LLM calls. Costs are in USD. Without dates the range is the last 30 days. start_date is inclusive and end_date exclusive, so for September 2026 pass 2026-09-01T00:00:00Z and 2026-10-01T00:00:00Z.

Without workspace the figures cover the whole organization, as the Cost Management page does for an organization admin; this needs the organization admin role. Use workspace for one workspace. In that organization view pipeline_name and Service names can't be used (they belong to a workspace); pass Service ids instead.

Narrow the figures with services, providers and api_keys. They combine: usage must match every kind you set, and any one value within a list.

Check is_cost_complete before reporting total_cost. When it is false, total_cost is a lower bound, not the final figure: say so, and name the models in unpriced_models (LLM calls with no price on file) and mention pending_generation_count (calls whose cost is still being calculated, which usually clears within a minute). total_requests counts queries, not individual LLM calls; one query can make several LLM calls.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str | None	The workspace name. Omit for the whole organization, which needs the organization admin role; then pipeline_name and Service names can't be used, only Service ids.	None
pipeline_name	str | None	Restrict to this pipeline. Omit for the whole workspace. Needs Pipelines read as well as Costs read.	None
start_date	str | None	Inclusive start as an ISO timestamp. Defaults to 30 days before end_date.	None
end_date	str | None	Exclusive end as an ISO timestamp. Defaults to no upper bound.	None
services	list[str] | None	Restrict to these Services (deployment in the API; a published Service endpoint, not a deployed pipeline, which is a pipeline). Each value is a Service name or its id, the key from get_cost_breakdown with group_by='deployment'. Looking a Service up by name needs Services read as well as Costs read; an id needs only Costs read.	None
providers	list[str] | None	Restrict to these providers. Use the provider ids from get_cost_breakdown with group_by='provider', such as bedrock_converse or openai, not their display names.	None
api_keys	list[str] | None	Restrict to these API keys. Use the key ids from get_cost_breakdown with group_by='api_key', never a key's secret token.	None

Returns:

Type	Description
CostTotals | str	The cost totals, or an error message.

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.activate_deployment async

activate_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
) -> Deployment | str

Re-activates a deployment's current active revision, marking it as desired to be served.

Use this to bring a deactivated deployment back online without pushing a new revision.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required

Returns:

Type	Description
Deployment | str	The updated deployment or error message.

deepset_mcp.tools.activate_deployment_revision async

activate_deployment_revision(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    revision_id: str,
) -> Deployment | str

Activates a revision, marking it as the deployment's desired served revision.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
revision_id	str	ID of the revision to activate.	required

Returns:

Type	Description
Deployment | str	The updated deployment or error message.

deepset_mcp.tools.add_deployment_tag async

add_deployment_tag(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    tag_name: str,
) -> list[str] | str

Adds a tag to a deployment. Each deployment supports at most three tags.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
tag_name	str	Tag to add (1-50 characters; letters, digits, spaces, underscores, hyphens).	required

Returns:

Type	Description
list[str] | str	The deployment's full tag list after the add, or error message.

deepset_mcp.tools.create_deployment async

create_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str,
    description: str | None = None,
    group_label: str | None = None,
    origin_pipeline_id: str | None = None,
    deployment_mode: DeploymentMode = MANAGED,
    service_level: DeploymentServiceLevel = DEVELOPMENT,
    idle_timeout_in_seconds: int | None = None,
    min_query_replica_count: int | None = None,
    max_query_replica_count: int | None = None,
    max_index_replica_count: int | None = None,
    cpu_request: str | None = None,
    cpu_limit: str | None = None,
    memory_request: str | None = None,
    memory_limit: str | None = None,
    gpu_limit_gigabyte: int | None = None,
) -> Deployment | str

Creates a new deployment (AI Gateway), optionally linked to a pipeline.

A deployment created without an origin_pipeline_id has no active revision until you call create_deployment_revision and activate_deployment_revision. Default service sizing follows Development unless explicit sizing fields are provided.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str	Name of the deployment.	required
description	str | None	Optional description.	None
group_label	str | None	Optional label used to group related deployments.	None
origin_pipeline_id	str | None	ID of the platform pipeline to link, if any.	None
deployment_mode	DeploymentMode	Execution mode, "MANAGED" or "SERVERLESS" (default "MANAGED").	MANAGED
service_level	DeploymentServiceLevel	Sizing tier, "PRODUCTION", "DEVELOPMENT", or "CUSTOM" (default "DEVELOPMENT").	DEVELOPMENT
idle_timeout_in_seconds	int | None	Seconds of inactivity before scaling down.	None
min_query_replica_count	int | None	Minimum number of query replicas.	None
max_query_replica_count	int | None	Maximum number of query replicas.	None
max_index_replica_count	int | None	Maximum number of index replicas.	None
cpu_request	str | None	Requested CPU per replica.	None
cpu_limit	str | None	CPU limit per replica.	None
memory_request	str | None	Requested memory per replica.	None
memory_limit	str | None	Memory limit per replica.	None
gpu_limit_gigabyte	int | None	GPU memory limit in gigabytes.	None

Returns:

Type	Description
Deployment | str	The created deployment or error message.

deepset_mcp.tools.create_deployment_revision async

create_deployment_revision(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    comment: str,
    config_yaml: str | None = None,
    source_version_id: str | None = None,
    source_type: DeploymentSourceType = PLATFORM_PIPELINE,
) -> DeploymentRevision | str

Pushes a new revision onto a deployment, e.g. from a platform pipeline version.

Creating a revision does not serve it automatically; call activate_deployment_revision to make it the deployment's served revision.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
comment	str	Comment describing the revision.	required
config_yaml	str | None	Inline pipeline configuration YAML, for an externally pushed revision.	None
source_version_id	str | None	ID of the source pipeline version, for a platform pipeline revision.	None
source_type	DeploymentSourceType	Where the revision's pipeline configuration comes from, "PLATFORM_PIPELINE" (default) or "EXTERNAL_PIPELINE".	PLATFORM_PIPELINE

Returns:

Type	Description
DeploymentRevision | str	The newly created revision or error message.

deepset_mcp.tools.deactivate_deployment async

deactivate_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
) -> Deployment | str

Marks a deployment as no longer desired to be served, keeping its active revision intact.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required

Returns:

Type	Description
Deployment | str	The updated deployment or error message.

deepset_mcp.tools.delete_deployment async

delete_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
) -> NoContentResponse | str

Deletes a deployment along with all of its revisions. This cannot be undone.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment to delete.	required

Returns:

Type	Description
NoContentResponse | str	Confirmation or error message.

deepset_mcp.tools.delete_deployment_tag async

delete_deployment_tag(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    tag_name: str,
) -> list[str] | str

Removes a tag from a deployment. Tag matching is case-insensitive.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
tag_name	str	Tag to remove.	required

Returns:

Type	Description
list[str] | str	The deployment's full tag list after removal, or error message.

deepset_mcp.tools.get_deployment async

get_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
) -> Deployment | str

Fetches details for a specific deployment, including its active revision and runtime status.

Parameters:

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

Returns:

Type	Description
Deployment | str	Deployment details or error message.

deepset_mcp.tools.get_deployment_metrics async

get_deployment_metrics(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    start_ms: int,
    end_ms: int,
) -> DeploymentMetrics | str

Fetches per-replica CPU/memory usage, resource limits, and replica counts for a deployment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
start_ms	int	Start of the time range, in unix milliseconds.	required
end_ms	int	End of the time range, in unix milliseconds.	required

Returns:

Type	Description
DeploymentMetrics | str	Deployment metrics or error message.

deepset_mcp.tools.get_deployment_revision async

get_deployment_revision(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    revision_id: str,
) -> DeploymentRevisionDetail | str

Fetches a single deployment revision, including the pipeline configuration YAML it serves.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
revision_id	str	ID of the revision to fetch.	required

Returns:

Type	Description
DeploymentRevisionDetail | str	The revision, including its config YAML, or error message.

deepset_mcp.tools.get_deployment_stats async

get_deployment_stats(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    days: int = 30,
    granularity: DeploymentStatsGranularity = DAY,
    time_zone: str = "UTC",
) -> DeploymentStatistics | str

Fetches query volume, outcome split, and run durations for a deployment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
days	int	Size of the rolling window, in days (1-90, default 30).	30
granularity	DeploymentStatsGranularity	Bucket width for the returned series, "DAY" (default) or "HOUR".	DAY
time_zone	str	IANA time zone used to bucket the series (default "UTC").	'UTC'

Returns:

Type	Description
DeploymentStatistics | str	Deployment statistics or error message.

deepset_mcp.tools.list_deployment_activity async

list_deployment_activity(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    after: str | None = None,
) -> PaginatedResponse[DeploymentEvent] | str

Lists activation and revision activity for a deployment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
after	str | None	The cursor to fetch the next page of results.	None

Returns:

Type	Description
PaginatedResponse[DeploymentEvent] | str	Paginated list of activity events or error message.

deepset_mcp.tools.list_deployment_revisions async

list_deployment_revisions(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    after: str | None = None,
) -> PaginatedResponse[DeploymentRevision] | str

Lists revisions of a deployment, i.e. the history of pipeline configurations it has served.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment.	required
after	str | None	The cursor to fetch the next page of results.	None

Returns:

Type	Description
PaginatedResponse[DeploymentRevision] | str	Paginated list of revisions or error message.

deepset_mcp.tools.list_deployment_tags async

list_deployment_tags(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str | None = None,
    order: str = "ASC",
) -> list[str] | str

Lists distinct tag strings attached to deployments in the workspace.

Useful for autocomplete when adding tags, or to see how deployments are currently grouped.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str | None	Case-insensitive substring filter on tag names.	None
order	str	Sort order for the returned tags, "ASC" or "DESC" (default "ASC").	'ASC'

Returns:

Type	Description
list[str] | str	List of distinct tag names or error message.

deepset_mcp.tools.list_deployments async

list_deployments(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    after: str | None = None,
    group_label: str | None = None,
    tags: list[str] | None = None,
) -> PaginatedResponse[Deployment] | str

Lists deployments (AI Gateways) in the currently configured deepset workspace.

A deployment serves a pipeline behind a stable endpoint, independent of the pipeline's own draft/version history.

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.	None
group_label	str | None	Filter deployments by group label.	None
tags	list[str] | None	Filter deployments by tags (matches if any tag is present).	None

Returns:

Type	Description
PaginatedResponse[Deployment] | str	Paginated list of deployments or error message.

deepset_mcp.tools.update_deployment async

update_deployment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    deployment_id: str,
    name: str | None = None,
    description: str | None = None,
    group_label: str | None = None,
    deployment_mode: DeploymentMode | None = None,
    service_level: DeploymentServiceLevel | None = None,
    idle_timeout_in_seconds: int | None = None,
    min_query_replica_count: int | None = None,
    max_query_replica_count: int | None = None,
    max_index_replica_count: int | None = None,
    cpu_request: str | None = None,
    cpu_limit: str | None = None,
    memory_request: str | None = None,
    memory_limit: str | None = None,
    gpu_limit_gigabyte: int | None = None,
) -> Deployment | str

Updates a deployment's metadata, sizing, or execution mode.

Only fields you provide are changed; omitted fields keep their current value.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
deployment_id	str	ID of the deployment to update.	required
name	str | None	New name for the deployment.	None
description	str | None	New description.	None
group_label	str | None	New group label.	None
deployment_mode	DeploymentMode | None	New execution mode, "MANAGED" or "SERVERLESS".	None
service_level	DeploymentServiceLevel | None	New sizing tier, "PRODUCTION", "DEVELOPMENT", or "CUSTOM".	None
idle_timeout_in_seconds	int | None	New idle timeout, in seconds.	None
min_query_replica_count	int | None	New minimum number of query replicas.	None
max_query_replica_count	int | None	New maximum number of query replicas.	None
max_index_replica_count	int | None	New maximum number of index replicas.	None
cpu_request	str | None	New requested CPU per replica.	None
cpu_limit	str | None	New CPU limit per replica.	None
memory_request	str | None	New requested memory per replica.	None
memory_limit	str | None	New memory limit per replica.	None
gpu_limit_gigabyte	int | None	New GPU memory limit in gigabytes.	None

Returns:

Type	Description
Deployment | str	The updated deployment or error message.

deepset_mcp.tools.list_doc_sections async

list_doc_sections() -> str

List the main sections of the deepset AI Platform documentation.

Use this to understand what documentation is available and help users navigate to the right section. Pass a section id to search_docs as section to limit search results to that part of the docs.

Returns:

Type	Description
str	A list of documentation sections with descriptions and URLs.

deepset_mcp.tools.search_docs async

search_docs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    query: str,
    section: str | None = None,
) -> 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
section	str | None	Optional documentation section id from list_doc_sections. Limits results to that section (applied to the returned hits, so it may return fewer results than an unfiltered search).	None

Returns:

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

deepset_mcp.tools.add_test_cases async

add_test_cases(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
    test_cases: list[NewTestCase],
    pipeline_name: str | None = None,
) -> Dataset | str

Adds test cases to the end of a Dataset. Replays nothing and costs nothing.

Each test case is either a recorded Session (session_id) or inputs, never both. A Session needs pipeline_name. A Session the Dataset already holds is skipped. To reuse test cases from another Dataset use copy_test_cases.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required
test_cases	list[NewTestCase]	The test cases to add, in order.	required
pipeline_name	str | None	The pipeline the Sessions were recorded on; required when a test case has a session_id.	None

Returns:

Type	Description
Dataset | str	The Dataset with all its test cases, or an error message.

deepset_mcp.tools.copy_test_cases async

copy_test_cases(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
    test_case_ids: list[str],
) -> Dataset | str

Copies test cases from any Dataset of the workspace to the end of this one.

Each copy keeps the Session or inputs, name, expected data and scripts, and gets its own id, so editing a copy leaves the original untouched. Find ids with get_dataset.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset to copy into.	required
test_case_ids	list[str]	The test cases to copy, in order.	required

Returns:

Type	Description
Dataset | str	The Dataset with all its test cases, or an error message.

deepset_mcp.tools.create_dataset async

create_dataset(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str,
    pipeline_name: str | None = None,
    test_cases: list[NewTestCase] | None = None,
) -> Dataset | str

Creates a Dataset, optionally with its first test cases. Replays nothing and costs nothing.

Each test case is either a recorded Session (session_id, find them with list_sessions) or inputs to send to the pipeline, never both. A Session needs pipeline_name, the pipeline it was recorded on. A Session sent twice becomes one test case. Add more later with add_test_cases. Then run it with create_experiment using the returned dataset_id.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str	What the Dataset is called.	required
pipeline_name	str | None	The pipeline the Sessions were recorded on; required when a test case has a session_id.	None
test_cases	list[NewTestCase] | None	The test cases to start with; none by default.	None

Returns:

Type	Description
Dataset | str	The created Dataset, or an error message.

deepset_mcp.tools.create_evaluator async

create_evaluator(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str,
    python_code: str,
    metric_group_ids: list[str] | None = None,
    new_metric_group_name: str | None = None,
) -> Evaluator | str

Creates an Evaluator from Python source and adds it to the workspace. Judged Metrics cost money when run.

Always validate new code first: run it on a real Session with try_evaluator and fix what it reports before saving. python_code is the Evaluation Function; its @metrics declaration names the Metrics it reports, and hub-api rejects code whose declaration it cannot read. Start from list_evaluator_templates rather than from scratch. The name must be unused in the workspace. The Evaluator scores nothing until a Metric Group runs it: add it to existing groups with metric_group_ids (each at the end of its set), to a new group with new_metric_group_name, or later with update_metric_group. Change it later with update_evaluator.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str	The Evaluator's name; must not exist in the workspace yet.	required
python_code	str	The Evaluation Function's Python source.	required
metric_group_ids	list[str] | None	Existing Metric Groups to add it to.	None
new_metric_group_name	str | None	Also creates a Metric Group of this name holding only this Evaluator.	None

Returns:

Type	Description
Evaluator | str	The created Evaluator, or an error message.

deepset_mcp.tools.create_experiment async

create_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str,
    dataset_id: str,
    metric_group_id: str,
    candidate_pipeline_name: str,
    candidate_pipeline_version_id: str,
    baseline_pipeline_name: str | None = None,
    baseline_pipeline_version_id: str | None = None,
    sessions_per_test_case: int = 1,
    replay_mode: Literal[
        "FIRST_USER_MESSAGE", "ALL_USER_MESSAGES"
    ] = "FIRST_USER_MESSAGE",
    reuse_sessions: bool = True,
    preview: bool = False,
) -> Experiment | ExperimentPlan | str

Creates an Experiment that compares a candidate pipeline version against a baseline.

Both sides are scored by the same Metric Group over the test cases of one Dataset. The baseline is either another pipeline version (give baseline_pipeline_name and baseline_pipeline_version_id together) or Recorded (leave both unset): a Recorded baseline reuses the Sessions each test case recorded, with nothing replayed. The candidate is always a pipeline version that will be replayed on each test case.

Creating costs money: it replays the pipeline on the customer's models, and then every Session is judged by the Metric Group's Evaluators, which are billed when they use an LLM. Call it first with preview=True: that starts nothing and returns, per side, how many Sessions are reused_sessions and how many replays_needed, plus cells (Sessions times Evaluators) against max_cells. Show that to the user and get a yes before creating for real. sessions_per_test_case sets how many Sessions each side scores per test case (1..50); existing Sessions on that version are reused and only the shortfall is replayed. Set reuse_sessions=False to replay every Session instead of reusing any, for example after a change outside the pipeline's configuration such as a secret; it costs more replays, so preview it. A Recorded baseline still scores the Dataset's own Sessions. Find ids with list_metric_groups (metric groups) and list_experiments (an existing Experiment's dataset_id). Read the running or finished Experiment with get_experiment_results; follow its progress with get_experiment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str	Human-readable name for the Experiment.	required
dataset_id	str	The Dataset's id (the UI's Dataset dropdown).	required
metric_group_id	str	The Metric Group id to score both sides with.	required
candidate_pipeline_name	str	Name of the candidate pipeline.	required
candidate_pipeline_version_id	str	The candidate pipeline version to replay.	required
baseline_pipeline_name	str | None	Baseline pipeline name; omit for a Recorded baseline.	None
baseline_pipeline_version_id	str | None	Baseline version id; required when baseline_pipeline_name is given.	None
sessions_per_test_case	int	Repetitions per test case (1..50, default 1).	1
replay_mode	Literal['FIRST_USER_MESSAGE', 'ALL_USER_MESSAGES']	FIRST_USER_MESSAGE replays the first turn only; ALL_USER_MESSAGES replays every turn.	'FIRST_USER_MESSAGE'
reuse_sessions	bool	False replays every Session each side scores and reuses none (default True).	True
preview	bool	True returns the plan (what would be reused and replayed) and creates nothing.	False

Returns:

Type	Description
Experiment | ExperimentPlan | str	The created Experiment, or with preview the plan, or an error message.

deepset_mcp.tools.create_metric_group async

create_metric_group(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    name: str,
    evaluator_ids: list[str],
    weights: list[MetricWeight] | None = None,
) -> MetricGroup | str

Creates a Metric Group: a named, ordered set of Evaluators to score Sessions of any pipeline with.

The group names Evaluators, not versions, so each run judges with their newest versions. Running it costs money if an Evaluator is judged. Find Evaluator ids with list_evaluators.

weights say how much each Metric counts toward the group's Composite, as {evaluator_id, metric_key, weight} entries. weight is a number above 0 and relative: weights are divided by their sum, so 2, 1, 1 count as 50%, 25%, 25%. Each Evaluator must be in the group, each metric_key must be one its newest version declares with a Normalized mean (a Score with both range and better, or a Label with a scale), and no pair may repeat; otherwise hub-api rejects the request. Without weights a group has no Composite. A stored weight with usable false and an unusable_reason means a newer Evaluator version dropped the Metric or its normalization: it is kept but no longer counts in new runs.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
name	str	The Metric Group's name.	required
evaluator_ids	list[str]	The Evaluators to run, in the order results show them (at least one).	required
weights	list[MetricWeight] | None	Optional Metric weights, as described above.	None

Returns:

Type	Description
MetricGroup | str	The created Metric Group, or an error message.

deepset_mcp.tools.delete_dataset async

delete_dataset(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
) -> str

Deletes a Dataset and all its test cases. This cannot be undone: get a yes first.

Experiments that used the Dataset keep their results but lose the link to it. hub-api refuses with a message while something else still uses the Dataset; relay that message. Afterwards every Experiment that used the Dataset can no longer change sides or rerun failed replays (hub-api answers 409).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required

Returns:

Type	Description
str	A confirmation, or an error message.

deepset_mcp.tools.delete_experiment async

delete_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
) -> str

Deletes an Experiment and its results. This cannot be undone: get a yes first.

The Sessions it reused, its replays and its scoring runs are kept, so later Experiments can reuse them.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id.	required

Returns:

Type	Description
str	A confirmation, or an error message.

deepset_mcp.tools.delete_metric_group async

delete_metric_group(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    metric_group_id: str,
) -> str

Deletes a Metric Group together with all its scoring runs. This cannot be undone: get a yes first.

The Evaluators themselves stay. hub-api refuses with a message while something else still uses the group; relay that message. Afterwards every Experiment that used the group can no longer change sides or rerun failed replays (hub-api answers 409).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
metric_group_id	str	The Metric Group's id.	required

Returns:

Type	Description
str	A confirmation, or an error message.

deepset_mcp.tools.get_dataset async

get_dataset(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
) -> Dataset | str

Fetches one Dataset with all its test cases, in the order an Experiment replays them.

Each test case has its test_case_id (for update_test_case, copy_test_cases and remove_test_cases), the session_id it replays or the inputs it sends, its expected data and its setup and cleanup source.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required

Returns:

Type	Description
Dataset | str	The Dataset, or an error message.

deepset_mcp.tools.get_evaluation_run async

get_evaluation_run(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    evaluation_run_id: str,
) -> EvaluationRun | str

Reads one Evaluation Run: its progress, or what the Evaluator found once it ended.

Use it to follow a run run_evaluator handed back while still going. status ENDED with outcome SUCCEEDED has metrics; ERRORED means the Evaluator's code broke (see error_detail); FAILED never completed and can be run again.

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
evaluation_run_id	str	The evaluation_run_id from run_evaluator or list_evaluation_runs.	required

Returns:

Type	Description
EvaluationRun | str	The Evaluation Run, or an error message.

deepset_mcp.tools.get_evaluation_try async

get_evaluation_try(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    try_id: str,
) -> TryReport | str

Reads an ad-hoc try that try_evaluator handed back while it was still running.

EXPIRED means the result aged out (tries are kept for an hour): run try_evaluator again.

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
try_id	str	The try_id from try_evaluator.	required

Returns:

Type	Description
TryReport | str	The try report, or an error message.

deepset_mcp.tools.get_evaluator async

get_evaluator(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    evaluator_id: str,
    version_id: str | None = None,
) -> Evaluator | EvaluatorVersion | str

Fetches one Evaluator, or one of its versions with the Python source.

Without version_id it returns the Evaluator with every version, newest first, each with the Metrics it declares but no source. With version_id it returns that version including its python_code; pass latest_version.evaluator_version_id to read the current source.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
evaluator_id	str	The Evaluator's id.	required
version_id	str | None	A version's id, to read that version's source.	None

Returns:

Type	Description
Evaluator | EvaluatorVersion | str	The Evaluator or the version, or an error message.

deepset_mcp.tools.get_experiment async

get_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
) -> ExperimentDetail | str

Reads one Experiment: its test cases and how far each side has got. Free to call.

Use it to follow an Experiment after create_experiment, update_experiment or a rerun, and to see why a side failed. status and each side's status go REPLAYING, SCORING, then ENDED or FAILED. Per side: run_counts (replays by status, failed ones can be replayed again), scoring_counts (evaluations; failed and errored ones can be judged again), error (why it could not be scored) and experiment_run_id (the scoring run, for get_experiment_run). The Sessions each side scored are not included; they are per test case in get_experiment_results. To retry what failed use rerun_failed_experiment; to see why one replay failed, read it with get_session_replay (its id is on the Session's row in get_experiment_run).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id, from list_experiments.	required

Returns:

Type	Description
ExperimentDetail | str	The Experiment, or an error message.

deepset_mcp.tools.get_experiment_results async

get_experiment_results(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
    max_test_cases: int = 100,
) -> ExperimentResultsReport | str

Reads an Experiment's results: each Metric, candidate against baseline, then each test case.

Find an Experiment with list_experiments. metrics has one entry per Metric of the Metric Group, in its order: each side's value (or labels for a Label), delta and delta_pct of the candidate over the baseline, better (which way a change is an improvement, null when undeclared), change (improved, regressed, unchanged or unknown), and how many Sessions errored, meaning the Evaluator's own code broke. A test case's value is the mean over its Sessions, and a Metric is averaged only over the paired_test_cases both sides have a value for, so check that count before trusting a delta. Say a Metric improved or regressed only from change; unknown means no judgement, so never infer a direction from the Metric's name. pipeline_metrics compares DURATION, TOKENS and COST the same way. Each test case lists the Sessions each side scored and, per Score Metric keyed {evaluator_id}:{metric_key}, each side's mean; that is where to look for the test cases behind a regression. Resolve evaluator ids to names with list_evaluators. Results are partial while status is REPLAYING or SCORING. headline gives each side's Composite (0 to 1, 1 best) and normalized_means. When comparable is false the two sides used different formulas: report no change between them and give incomparable_reason; each side's composite_weights shows the formula it used. aggregates gives each Metric over every Session a side scored, not just the paired test cases: each side's whole-run entry (a Score's mean, a Label's shares), delta, share_deltas for a Label and change. Empty until a side's scoring runs end.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id.	required
max_test_cases	int	Most test cases to return; metrics still cover every test case.	100

Returns:

Type	Description
ExperimentResultsReport | str	The results, or an error message.

deepset_mcp.tools.get_experiment_run async

get_experiment_run(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    metric_group_id: str,
    run_id: str,
    max_rows: int = 100,
    origin: Literal["SERVICE", "PIPELINE_RUN", "PLAYGROUND"]
    | None = None,
    deployment_id: str | None = None,
    pipeline_version_id: str | None = None,
    session_id: str | None = None,
) -> ExperimentRunReport | str

Reads one scoring run: how its cells ended, a summary per Metric, then the grid rows.

A scoring run is a Metric Group judging chosen Sessions of one pipeline. Find one with list_metric_groups (last_run) or list_experiments (a side's scoring_runs). It judges each chosen Session with each Evaluator; one cell per pair. counts says how the cells ended: errored is the Evaluator's own code breaking (see the cell's error_detail), not a low Metric; failed is a cell that never ran and can be retried. metrics summarises each Evaluator's Metric over every row, rows past max_rows included: mean, min and max for a Score, a count per label for a Label, and how often it did not apply. Each row is a Session with its cells; a cell's metrics carry the value per address (session, turn/2, ...) and the rationale the Evaluator wrote, which is what to group failures by. run.selection says whether the Sessions were SAMPLED or HAND_PICKED; only sampled runs say anything about traffic as a whole. composite is the Metric Group's single number for the run, 0 to 1 with 1 best, from normalized_means (each Metric on that scale) weighted by run.composite_weights, the formula the run started with. When it has no value it says reason and lists the Metrics that block it in missing. aggregate is the API's whole-run result per Metric: how its Sessions fell out (valued, errored, failed, pending, ...), coverage and the Metric's mean or label shares, in the units it declares; it is null until the run ends. usage is what the pipeline spent on the run's Sessions (tokens, duration, cost in USD, null unless cost_status is priced). evaluator_versions says which version of each Evaluator judged and what its Metrics declare. The filters keep only the cells whose Session's origin, Service or pipeline version match (a cell still running has no origin and matches none): they narrow counts, rows and metrics, but not aggregate, usage, normalized_means or composite, which stay whole-run.

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
metric_group_id	str	The id of the Metric Group the run scored with.	required
run_id	str	The run's id.	required
max_rows	int	Most rows to return; the summaries still cover every row.	100
origin	Literal['SERVICE', 'PIPELINE_RUN', 'PLAYGROUND'] | None	Only cells whose Session came from a Service, the pipeline's own API, or the Playground.	None
deployment_id	str | None	Only cells whose Session this Service served.	None
pipeline_version_id	str | None	Only cells whose Session this pipeline version served.	None
session_id	str | None	Only this Session's row.	None

Returns:

Type	Description
ExperimentRunReport | str	The run report, or an error message.

deepset_mcp.tools.get_session_replay async

get_session_replay(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    replay_run_id: str,
) -> SessionReplayRun | str

Reads one replay run. Free to call.

Experiment support, for when you need it: to see why an Experiment's replay failed or looks wrong, read its run. Get the id from a row's session_replay_run_id in get_experiment_run (the row is the Session the replay produced), or from replay_session. The run has status (CREATED, STARTED, ENDED or FAILED), error_detail when it failed, setup_logs and cleanup_logs from the setup and cleanup steps, session_id (the new Session the replay produced), source_session_id (the Session it replayed), test_case_id (the Dataset test case it was for, if any), and the trace_ids it produced. Only a FAILED run is retryable, with rerun_failed_experiment (rerun="replays").

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
replay_run_id	str	The replay run's session_replay_run_id.	required

Returns:

Type	Description
SessionReplayRun | str	The replay run, or an error message.

deepset_mcp.tools.list_datasets async

list_datasets(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str | None = None,
    limit: int = 50,
) -> list[DatasetSummary] | str

Lists the workspace's Datasets, newest first, without their test cases.

A Dataset is a named list of test cases (a recorded Session or a set of inputs, with optional expected data) that an Experiment replays against a pipeline version. Each entry has its dataset_id, test_case_count and the pipeline_ids its test cases belong to. Read the test cases with get_dataset; pass dataset_id to create_experiment. The API has no paging: a result of exactly limit Datasets may be cut off; raise limit (at most 200) or narrow with 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 | None	Only Datasets with a test case on this pipeline, when given.	None
limit	int	Most Datasets to return (at most 200).	50

Returns:

Type	Description
list[DatasetSummary] | str	The Datasets, or an error message.

deepset_mcp.tools.list_evaluation_runs async

list_evaluation_runs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    limit: int = 50,
) -> list[EvaluationRun] | str

Lists a pipeline's Evaluation Runs, newest first: one Evaluator version judging one Session each.

Includes the runs behind a scoring run's cells and the ones run_evaluator made. Each has its session_id, evaluator_version_id, outcome and metrics. Read one with get_evaluation_run.

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
limit	int	Most runs to return (at most 200). The API has no further paging: a result of exactly this many may be cut off.	50

Returns:

Type	Description
list[EvaluationRun] | str	The runs, or an error message.

deepset_mcp.tools.list_evaluator_templates async

list_evaluator_templates(
    *, client: AsyncClientProtocol, workspace: str
) -> list[EvaluatorTemplate] | str

Lists the built-in Evaluator templates: ready-made Evaluation Functions to start from.

They cover agent efficiency, agent quality, RAG quality and retrieval quality. Each has a key, name, category, its python_code and the Metrics it declares. A template with a judge_model asks a model per Session, so running it costs money. expected_columns are the columns of a Dataset test case's expected data it reads. To use one, pass its name and python_code to create_evaluator; the copy is yours and does not follow the template.

Parameters:

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

Returns:

Type	Description
list[EvaluatorTemplate] | str	The templates, or an error message.

deepset_mcp.tools.list_evaluators async

list_evaluators(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    limit: int = 200,
    archived: bool | None = None,
) -> list[Evaluator] | str

Lists the Evaluators in the workspace.

An Evaluator is a versioned Python function that judges a Session and reports named Metrics. Each entry carries its newest version's id and the Metrics that version declares (name, shape, grain and, for a closed Label, its vocabulary and, if it declares one, its scale; for a Score, its range and better), but not the source. Evaluators belong to the workspace, not to a pipeline; a Metric Group picks which ones a scoring run judges with. The API has no paging: a result of exactly limit Evaluators may be cut off, and Evaluators past the 200 cap are reachable only by splitting the list with archived.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
limit	int	Most Evaluators to return (at most 200).	200
archived	bool | None	true for only archived Evaluators, false for only the others; omit for both.	None

Returns:

Type	Description
list[Evaluator] | str	The Evaluators, or an error message.

deepset_mcp.tools.list_experiment_runs async

list_experiment_runs(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    metric_group_id: str | None = None,
    session_id: str | None = None,
    limit: int = 50,
) -> list[ExperimentRun] | str

Lists scoring runs: a Metric Group's on one pipeline, or every one that judged a given Session.

A scoring run is a Metric Group judging chosen Sessions of one pipeline, outside any Experiment (see start_experiment_run); the runs an Experiment makes are listed too. Give metric_group_id for that group's runs, or session_id for the runs, of any Metric Group, that judged that Session; each run names its Metric Group in pipeline_experiment_id. Newest first, without their grids: status says whether the fan-out finished, not whether every cell succeeded, window is what a window run judged and resolved_sessions how many Sessions it had. Read one run's grid with get_experiment_run.

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
metric_group_id	str | None	List this Metric Group's runs. Give this or session_id.	None
session_id	str | None	List the runs that judged this Session. Give this or metric_group_id.	None
limit	int	Most runs to return (at most 200). The API has no further paging: a result of exactly this many may be cut off.	50

Returns:

Type	Description
list[ExperimentRun] | str	The runs, or an error message.

deepset_mcp.tools.list_experiments async

list_experiments(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str | None = None,
    limit: int = 50,
) -> list[Experiment] | str

Lists the workspace's Experiments, newest first.

An Experiment compares a candidate pipeline version against a baseline on the test cases of one Dataset: each side gets its Sessions (reused, or replayed against its version) and is scored by the same Metric Group. The baseline is another version, or, when recorded, the Sessions the Dataset recorded. status and each side's status go REPLAYING, SCORING, then ENDED or FAILED; a side's error says why it failed and scoring_counts how its evaluations ended. Read how the candidate did against the baseline with get_experiment_results. To read one side's scoring run cell by cell, pass its scoring_runs[].experiment_run_id, that entry's pipeline_id resolved to a name with list_pipelines, and the Experiment's metric_group_id to get_experiment_run. The API has no paging: a result of exactly limit Experiments may be cut off; raise limit (at most 200) or narrow with 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 | None	Only Experiments with either side on this pipeline, when given.	None
limit	int	Most Experiments to return (at most 200).	50

Returns:

Type	Description
list[Experiment] | str	The Experiments, or an error message.

deepset_mcp.tools.list_metric_groups async

list_metric_groups(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str | None = None,
    limit: int = 200,
) -> list[MetricGroupSummary] | str

Lists the workspace's Metric Groups, newest first.

A Metric Group is a named, ordered set of Evaluators. It belongs to the workspace, not to a pipeline: a scoring run judges chosen Sessions of one pipeline with it, and an Experiment scores both its sides with one. With pipeline_name, each entry's last_run is its newest scoring run on that pipeline without the grid (status, selection, timing), or null when it never ran there; read a run's results with get_experiment_run. weights says how much each Metric counts toward the group's Composite (empty: no Composite); a weight with usable false says in unusable_reason why it will not count in a new run. The API has no paging: a result of exactly limit groups may be cut off (at most 200 are ever reachable).

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
pipeline_name	str | None	A pipeline to attach each Metric Group's most recent scoring run on.	None
limit	int	Most Metric Groups to return (at most 200). With pipeline_name each one costs a call.	200

Returns:

Type	Description
list[MetricGroupSummary] | str	The Metric Groups, or an error message.

deepset_mcp.tools.list_sessions async

list_sessions(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    origin: Literal["SERVICE", "PIPELINE_RUN", "PLAYGROUND"]
    | None = None,
    deployment_id: str | None = None,
    pipeline_version_id: str | None = None,
    revision_id: str | None = None,
    since: str | None = None,
    until: str | None = None,
    limit: int = 50,
    cursor: str | None = None,
) -> SessionList | str

Lists a pipeline's Sessions that a scoring run can judge, newest last activity first.

A Session is the turns that share a search_session_id; a run without one is a single-turn Session named by its query_id. Only Sessions whose every turn still has its trace are listed. session_id is the id a scoring run takes. To find Sessions that went wrong (a failed turn, negative feedback), use list_pipeline_traces with an OData filter instead and take each row's search_session_id, or its query_id when that is empty.

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
origin	Literal['SERVICE', 'PIPELINE_RUN', 'PLAYGROUND'] | None	Only Sessions whose every turn came from a Service, the pipeline's own API, or the Playground.	None
deployment_id	str | None	Only Sessions whose every turn this Service served.	None
pipeline_version_id	str | None	Only Sessions whose every turn this pipeline version served.	None
revision_id	str | None	Only Sessions whose every turn this Service revision served. Exact where a version is not: one version can be pushed to a Service more than once.	None
since	str | None	ISO-8601 time; only Sessions last active at or after it.	None
until	str | None	ISO-8601 time; only Sessions last active at or before it.	None
limit	int	Most Sessions per page (at most 200). A page can hold fewer and still have a next.	50
cursor	str | None	The next value of the previous page.	None

Returns:

Type	Description
SessionList | str	One page of Sessions, or an error message.

deepset_mcp.tools.remove_test_cases async

remove_test_cases(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
    test_case_ids: list[str],
) -> Dataset | str

Removes test cases from a Dataset. Destructive: the removed test cases are gone, so get a yes first.

Ids that are not in the Dataset are ignored.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required
test_case_ids	list[str]	The test cases to remove.	required

Returns:

Type	Description
Dataset | str	The Dataset with the test cases left, or an error message.

deepset_mcp.tools.replay_session async

replay_session(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    session_id: str,
    pipeline_version_id: str,
    replay_mode: Literal[
        "FIRST_USER_MESSAGE", "ALL_USER_MESSAGES"
    ]
    | None = None,
    setup_source: str | None = None,
    cleanup_source: str | None = None,
    wait_seconds: int = 300,
) -> SessionReplayRun | str

Replays one Session against a pipeline version into a new Session. Costs money.

Experiment support, for when you need it: to reproduce or retry the replay of one test case that failed or looks wrong, replay that test case's Session on the version the Experiment's side uses. It is a paid pipeline run on the customer's models: say what it costs and get a yes first. The replay is not linked to the Experiment, so the new Session is not added to it and changes none of its results. To retry an Experiment's failed replays inside the Experiment, use rerun_failed_experiment with rerun="replays". The source Session and the deployed pipeline are untouched.

FIRST_USER_MESSAGE replays the first turn only; ALL_USER_MESSAGES replays every turn of a chat in order. Leave it unset to use the server's default (the first turn), and say so when reporting. The run's session_id is the new Session; judge it with try_evaluator. If status is still CREATED or STARTED the wait ran out: poll get_session_replay with its session_replay_run_id. When it is FAILED, read error_detail and the logs.

setup_source and cleanup_source are optional Python run around the pipeline in an isolated worker. Setup must define exactly one public top-level function taking no arguments and returning a mapping with optional env (dict[str, str]), inputs (dict[str, Any], keyed by the pipeline's declared input names) and logs (list[str]); its env and inputs take precedence over the Session's own. Cleanup runs even when the replay failed; it must define one public top-level function taking the setup's return value (None without a setup) and returning a mapping with optional logs. Helpers must be underscore-prefixed or imported. Omit either to skip that step.

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
session_id	str	The Session to replay: a search_session_id, or a single-turn run's query_id.	required
pipeline_version_id	str	The pipeline version to replay against, e.g. the Experiment side's version.	required
replay_mode	Literal['FIRST_USER_MESSAGE', 'ALL_USER_MESSAGES'] | None	FIRST_USER_MESSAGE or ALL_USER_MESSAGES; unset uses the server's default.	None
setup_source	str | None	Python source run before the pipeline; unset skips the step.	None
cleanup_source	str | None	Python source run after the pipeline; unset skips the step.	None
wait_seconds	int	How long to wait for the replay before handing back the run to poll.	300

Returns:

Type	Description
SessionReplayRun | str	The replay run, with the new Session's session_id, or an error message.

deepset_mcp.tools.rerun_failed_experiment async

rerun_failed_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
    rerun: Literal[
        "evaluations", "replays"
    ] = "evaluations",
) -> Experiment | str

Retries what failed in an Experiment. Costs money: judges or replays again.

rerun="evaluations" judges again the evaluations a side's scoring run left failed or errored (see scoring_counts in get_experiment), reusing every one that succeeded; it bills only those Evaluators again. rerun="replays" replays again the replays that failed (run_counts.failed), reusing every Session that exists, then scores that side again, which bills the new Sessions' replays and evaluations. hub-api refuses with a message when nothing failed or while a side is still running. Follow progress with get_experiment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id.	required
rerun	Literal['evaluations', 'replays']	Which failures to retry: "evaluations" (default) or "replays".	'evaluations'

Returns:

Type	Description
Experiment | str	The Experiment, or an error message.

deepset_mcp.tools.rescore_experiment async

rescore_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
) -> Experiment | str

Scores both sides of an Experiment again with the Metric Group as it is now. Costs money.

Use it after changing the Metric Group's Evaluators or weights (update_metric_group, update_evaluator). Every Session is judged again, so every evaluation is billed again; the Sessions are not replayed. hub-api refuses with a message while a side is still running or if no side has been scored. Follow progress with get_experiment, then read get_experiment_results.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id.	required

Returns:

Type	Description
Experiment | str	The Experiment, or an error message.

deepset_mcp.tools.run_evaluator async

run_evaluator(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    evaluator_version_id: str,
    session_id: str,
    wait_seconds: int = 120,
) -> EvaluationRun | str

Runs one Evaluator version on one Session and keeps the result. A judged Evaluator costs money.

Unlike try_evaluator, which runs source you send and stores nothing, this runs a saved Evaluator version and stores an Evaluation Run that shows in list_evaluation_runs and in the Metric's history over time. Use it to judge one Session with an Evaluator that already exists; to judge many Sessions with a Metric Group use start_experiment_run. An Evaluator that judges with a model costs a model call per judged turn on the customer's provider, so say so and get a yes first. Find the version id with get_evaluator (latest_version or versions) and the Session with list_sessions.

outcome ERRORED means the Evaluator's code broke: read error_detail. metrics are the values per address with their rationales. If status is still CREATED or STARTED the wait ran out: poll get_evaluation_run with the evaluation_run_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 the Session belongs to.	required
evaluator_version_id	str	The exact Evaluator version to run.	required
session_id	str	The Session to judge: a search_session_id, or a single-turn run's query_id.	required
wait_seconds	int	How long to wait for the result before handing back the id to poll.	120

Returns:

Type	Description
EvaluationRun | str	The Evaluation Run, or an error message.

deepset_mcp.tools.set_evaluator_archived async

set_evaluator_archived(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    evaluator_id: str,
    archived: bool,
) -> Evaluator | str

Archives or unarchives an Evaluator. Nothing is deleted.

An archived Evaluator keeps its versions and name, and its Metric Groups still score with it; it only shows an archived_at time. Use it to retire an Evaluator without breaking history.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
evaluator_id	str	The Evaluator's id.	required
archived	bool	True to archive it, False to unarchive it.	required

Returns:

Type	Description
Evaluator | str	The Evaluator, or an error message.

deepset_mcp.tools.start_experiment_run async

start_experiment_run(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    metric_group_id: str,
    session_ids: list[str] | None = None,
    window_from: str | None = None,
    window_to: str | None = None,
    origin: Literal["SERVICE", "PIPELINE_RUN", "PLAYGROUND"]
    | None = None,
    deployment_id: str | None = None,
    pipeline_version_id: str | None = None,
    revision_id: str | None = None,
    reuse: Literal[
        "RERUN_ALL", "REUSE_SUCCEEDED"
    ] = "RERUN_ALL",
    selection: Literal[
        "SAMPLED", "HAND_PICKED"
    ] = "SAMPLED",
    focus: dict[str, list[str]] | None = None,
    preview: bool = False,
) -> ExperimentRunAccepted | ExperimentRunPreview | str

Scores a pipeline's Sessions with a Metric Group, outside any Experiment. Costs money.

Every Evaluator of the Metric Group judges every chosen Session, so the run has Sessions times Evaluators cells, and an Evaluator that judges with a model is billed per judged turn on the customer's provider. Name the Sessions in session_ids (find them with list_sessions), or give a window of time: window_from and window_to together, optionally narrowed by origin, deployment_id, pipeline_version_id and revision_id, judge every Session whose last activity falls in it. The server resolves the window to its Sessions when the run starts. Give session_ids or a window, never both. A window run is always SAMPLED and cannot take focus; it is refused when it has more Sessions or cells than the ceiling.

Preview first: preview=True with a window starts nothing and returns sessions, evaluators and cells (the judge calls it would make) against the ceiling. Show that to the user and get a yes before starting for real. There is no preview for named Sessions: their cells are the number of Sessions times the Metric Group's Evaluators.

The run is queued, not finished: poll it with get_experiment_run (counts, then the grid), and find earlier runs with list_experiment_runs. reuse REUSE_SUCCEEDED judges only what this Metric Group has not already judged successfully, which makes re-running after a partial failure cheap; RERUN_ALL judges everything again. selection HAND_PICKED marks Sessions chosen because they looked wrong, which keeps the run out of trends and exports; use it for named Sessions that are not a sample of the traffic. A focus makes it HAND_PICKED.

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 whose Sessions are judged.	required
metric_group_id	str	The Metric Group to judge with (see list_metric_groups).	required
session_ids	list[str] | None	The Sessions to judge: search_session_id values, or a single-turn run's query_id.	None
window_from	str | None	Window start, ISO 8601 with a timezone: last activity at or after it.	None
window_to	str | None	Window end, ISO 8601 with a timezone, not in the future: last activity at or before it.	None
origin	Literal['SERVICE', 'PIPELINE_RUN', 'PLAYGROUND'] | None	Window filter: only Sessions from SERVICE, PIPELINE_RUN or PLAYGROUND.	None
deployment_id	str | None	Window filter: only Sessions this Service served.	None
pipeline_version_id	str | None	Window filter: only Sessions this pipeline version served.	None
revision_id	str | None	Window filter: only Sessions this Service revision served.	None
reuse	Literal['RERUN_ALL', 'REUSE_SUCCEEDED']	RERUN_ALL (default) or REUSE_SUCCEEDED.	'RERUN_ALL'
selection	Literal['SAMPLED', 'HAND_PICKED']	SAMPLED (default) or HAND_PICKED.	'SAMPLED'
focus	dict[str, list[str]] | None	Per Session id, the turns to judge by query_id; a Session left out is judged on every turn.	None
preview	bool	True counts what the window would judge and starts nothing.	False

Returns:

Type	Description
ExperimentRunAccepted | ExperimentRunPreview | str	The queued run (pipeline_experiment_run_id, cells), or with preview the counts, or an error.

deepset_mcp.tools.try_evaluator async

try_evaluator(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    pipeline_name: str,
    python_code: str,
    session_id: str,
    test_case_id: str | None = None,
    wait_seconds: int = 120,
) -> TryReport | str

Tries Evaluator source on one Session and returns what it found. Persists nothing.

Use it to check a draft before showing it as ready, and to judge a replayed Session against its source. The source is an Evaluation Function: a Python function that reads one Session and reports named Metrics declared with @metrics. To try a saved Evaluator, read a version's python_code with get_evaluator and pass it. A try that judges with a model costs a model call per judged turn on the customer's provider.

test_case_id hands the Evaluation Function that Dataset test case's expected data, so a correctness Evaluator can be tried on any Session; leave it out to use the test case the Session replayed, if any.

outcome ERRORED means the code broke: read error_detail and fix it. metrics are the values per address with their rationales. trace_summary says which Session Tools the evaluator called. If status is RUNNING the wait ran out: poll get_evaluation_try.

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 the Session belongs to.	required
python_code	str	The Evaluation Function's source.	required
session_id	str	The Session to judge: a search_session_id, or a single-turn run's query_id.	required
test_case_id	str | None	A Dataset test case whose expected data the Evaluation Function receives.	None
wait_seconds	int	How long to wait for the result before handing back the id to poll.	120

Returns:

Type	Description
TryReport | str	The try report, or an error message.

deepset_mcp.tools.update_dataset async

update_dataset(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
    name: str,
) -> Dataset | str

Renames a Dataset. Change its test cases with the test case tools.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required
name	str	The new name.	required

Returns:

Type	Description
Dataset | str	The Dataset, or an error message.

deepset_mcp.tools.update_evaluator async

update_evaluator(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    evaluator_id: str,
    name: str | None = None,
    python_code: str | None = None,
) -> Evaluator | str

Renames an Evaluator, saves new source as a new version, or both. Send only what changes.

New source adds a version; the Evaluator's Metric Groups judge with the newest version from the next run on, and past runs keep the version they used. Validate the new code with try_evaluator first. Source the Evaluator already had in its history adds no version, so reverting is safe. hub-api rejects code that changes what an existing Metric measures (its shape, grain or range, a narrowed vocabulary), and a changed declaration can make a Metric Group weight unusable: check weights with list_metric_groups afterwards. Read the current source with get_evaluator.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
evaluator_id	str	The Evaluator's id.	required
name	str | None	The new name; must not be taken.	None
python_code	str | None	The new Python source.	None

Returns:

Type	Description
Evaluator | str	The Evaluator, or an error message.

deepset_mcp.tools.update_experiment async

update_experiment(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    experiment_id: str,
    name: str | None = None,
    candidate_pipeline_name: str | None = None,
    candidate_pipeline_version_id: str | None = None,
    baseline_pipeline_name: str | None = None,
    baseline_pipeline_version_id: str | None = None,
    recorded_baseline: bool = False,
    preview: bool = False,
) -> Experiment | ExperimentUpdatePlan | str

Renames an Experiment or changes its candidate or baseline. Changing a side costs money.

Send only what changes. A changed side is planned again as on a new Experiment: Sessions that already exist on it are reused, the rest are replayed, and it is judged again once they have finished; its previous scoring run is stopped and the other side is left alone. Only renaming costs nothing. Call it first with preview=True: that changes nothing and returns, for each changed side, reused_sessions and replays_needed (a side left alone is null). Show that to the user and get a yes before changing for real. Follow progress with get_experiment.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
experiment_id	str	The Experiment's id.	required
name	str | None	A new name.	None
candidate_pipeline_name	str | None	Pipeline of the new candidate; give it with its version id.	None
candidate_pipeline_version_id	str | None	The new candidate version.	None
baseline_pipeline_name	str | None	Pipeline of the new baseline; give it with its version id.	None
baseline_pipeline_version_id	str | None	The new baseline version.	None
recorded_baseline	bool	True makes the baseline the Dataset's recorded Sessions, with nothing replayed.	False
preview	bool	True returns the plan and changes nothing.	False

Returns:

Type	Description
Experiment | ExperimentUpdatePlan | str	The updated Experiment, or with preview the plan, or an error message.

deepset_mcp.tools.update_metric_group async

update_metric_group(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    metric_group_id: str,
    name: str,
    evaluator_ids: list[str],
    weights: list[MetricWeight] | None = None,
) -> MetricGroup | str

Replaces a Metric Group's name and Evaluator set, and optionally its Metric weights.

This is a full replace of name and Evaluators: send every Evaluator the group keeps, in order (read them with list_metric_groups). Past runs are unaffected; each recorded the versions it used, and a run's Composite keeps the weights it started with, so edits change only later runs. Leave weights out to keep the stored weights of the Evaluators that stay (those of removed Evaluators are dropped); send an empty list to clear them all, which removes the Composite.

weights say how much each Metric counts toward the group's Composite, as {evaluator_id, metric_key, weight} entries. weight is a number above 0 and relative: weights are divided by their sum, so 2, 1, 1 count as 50%, 25%, 25%. Each Evaluator must be in the group, each metric_key must be one its newest version declares with a Normalized mean (a Score with both range and better, or a Label with a scale), and no pair may repeat; otherwise hub-api rejects the request. Without weights a group has no Composite. A stored weight with usable false and an unusable_reason means a newer Evaluator version dropped the Metric or its normalization: it is kept but no longer counts in new runs.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
metric_group_id	str	The Metric Group's id.	required
name	str	The name to keep or change to.	required
evaluator_ids	list[str]	Every Evaluator the group keeps, in order (at least one).	required
weights	list[MetricWeight] | None	Replaces the stored weights; None keeps them, [] clears them.	None

Returns:

Type	Description
MetricGroup | str	The Metric Group, or an error message.

deepset_mcp.tools.update_test_case async

update_test_case(
    *,
    client: AsyncClientProtocol,
    workspace: str,
    dataset_id: str,
    test_case_id: str,
    name: str | None = None,
    inputs: dict[str, Any] | None = None,
    expected: dict[str, Any] | None = None,
    setup_source: str | None = None,
    cleanup_source: str | None = None,
    clear: list[
        Literal[
            "expected", "setup_source", "cleanup_source"
        ]
    ]
    | None = None,
) -> TestCase | str

Changes one test case of a Dataset. Fields you leave out are kept.

inputs replaces the inputs and works only on a test case created with inputs, not on a Session-based one. expected replaces the expected data.

Parameters:

Name	Type	Description	Default
client	AsyncClientProtocol	The async client for API communication.	required
workspace	str	The workspace name.	required
dataset_id	str	The Dataset's id.	required
test_case_id	str	The test case's id.	required
name	str | None	The new name.	None
inputs	dict[str, Any] | None	The new pipeline inputs, as {name: value}.	None
expected	dict[str, Any] | None	The new expected data.	None
setup_source	str | None	New Python source that runs before every replay.	None
cleanup_source	str | None	New Python source that runs after every replay.	None
clear	list[Literal['expected', 'setup_source', 'cleanup_source']] | None	Fields to remove from the test case.	None

Returns:

Type	Description
TestCase | str	The test case, or an 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,
    updated_index_name: str | None = None,
    yaml_configuration: str | None = None,
    description: str | None = None,
    max_allowed_batch_size: int | None = None,
    max_index_replica_count: int | None = None,
    gpu_enabled: bool | None = None,
    capture_traces: bool | None = None,
    instance_size: Literal["small", "medium", "large", "xl"]
    | None = None,
    file_name_prefix_filter: str | None = None,
    file_meta_filter: MetaFilterConditions | None = None,
    skip_validation_errors: bool = True,
) -> Index | IndexOperationWithErrors | str

Updates an index in the specified workspace.

Only the fields you pass are changed; a field left as None is not touched (it is not cleared server-side).

Pass yaml_configuration to replace the index's YAML. When provided, pass the complete, updated configuration (not just the changed parts); it is validated before being applied. If validation fails and skip_validation_errors is False, it returns error messages.

All other parameters are index settings that can be updated independently of the YAML:

• updated_index_name: rename the index.
• description: new description.
• max_allowed_batch_size: cap the number of files indexed per batch (1-500). Lower values reduce the chance that heavy files exceed the queue timeout and get retried.
• max_index_replica_count: maximum number of index replicas (1-10).
• gpu_enabled: enable or disable GPU acceleration.
• capture_traces: record an indexing trace for every file queued for this index.
• instance_size: pod size used to index files ("small", "medium", "large", or "xl").
• file_name_prefix_filter: prefix pattern (e.g. "myprefix*") selecting which files are indexed. Can only be updated while the index is not deployed.
• file_meta_filter: metadata conditions (field/operator/value, AND-combined) selecting which files are indexed. Can only be updated while the index is not deployed.

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
updated_index_name	str | None	Optional new name for the index.	None
yaml_configuration	str | None	Optional complete, updated YAML configuration for the index.	None
description	str | None	Optional new description.	None
max_allowed_batch_size	int | None	Optional per-pipeline cap on files indexed per batch (1-500).	None
max_index_replica_count	int | None	Optional max number of index replicas (1-10).	None
gpu_enabled	bool | None	Optional toggle for GPU acceleration.	None
capture_traces	bool | None	Optional toggle for recording an indexing trace per queued file.	None
instance_size	Literal['small', 'medium', 'large', 'xl'] | None	Optional pod size: "small", "medium", "large", or "xl".	None
file_name_prefix_filter	str | None	Optional file-name prefix pattern filter.	None
file_meta_filter	MetaFilterConditions | None	Optional metadata conditions filtering which files are indexed.	None
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,
    include_price: bool = False,
) -> 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
include_price	bool	If True, each model also carries its effective price in USD per 1,000 tokens (input, output and cache prices), with the workspace's and organization's custom prices applied. Requires read access to costs. Models without a known price have no price, e.g. Azure models that are only identified by their deployment name. Defaults to False.	False

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.list_organizations async

list_organizations(
    *, client: AsyncClientProtocol
) -> list[dict[str, Any]] | str

Lists the organizations the user belongs to.

Use this when the user belongs to several organizations and wants to work in a specific one. Pass the returned 'organization_id' as the 'organization_id' argument of other tools to run them in that organization. Without it, the default organization is used. Only works when connected through OAuth: API keys are bound to a single organization, so there is nothing to choose.

Parameters:

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

Returns:

Type	Description
list[dict[str, Any]] | str	List of organizations with 'organization_id' and 'name', or error message.

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.

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,
    workspace: str | None = None,
    limit: int = 10,
    after: str | None = None,
) -> EnvironmentSecretList | str

Lists all secrets available in the user's deepset organization or in a specific workspace.

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
workspace	str | None	Optional workspace name. If provided, lists the secrets available in this workspace.	None
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.