MCP interface reference#

The MCP interface consists of startup-generated structured tools, one optional raw argv tool, one read-only resource, and a common execution result.

Generated tools#

Each representable terminal argparse command receives one canonical tool. Tool names begin with conda_ and join the canonical command path with underscores, such as conda_info or conda_env_create. Aliases are metadata on the canonical tool rather than separate tools.

Input schemas preserve supported argparse behavior, including:

required and optional values
strings, integers, numbers, booleans, counts, and arrays
choices and repeated options
positional order
mutually exclusive groups
nested commands
opaque passthrough arrays for greedy plugin parsers

Unsupported parser actions mark an affected command as raw-only. Generated string positionals reject option-like values. Use raw argv when a command intentionally requires such a value.

Generated tool metadata includes the canonical conda path and aliases. MCP annotations describe read-only, destructive, idempotent, and open-world behavior. The server enforces policy independently of those annotations.

Conda completion metadata tool#

conda_cli_command is listed when the target plugin inventory contains conda-completion. Version 0.3 or newer supplies the public API used to read one command from that target installation’s generated completion.msgpack. The tool reports older versions as unavailable and never regenerates the file.

The optional command_path input is an array of canonical command tokens. An empty array selects the root. For example:

{
  "command_path": ["env", "list"]
}

The result includes command options, positionals, direct subcommands, exclusive groups, completion types and rules, runtime-source definitions, executable-alias resolution, manifest metadata, and plugin-hash staleness. Package-name and package-version caches are not returned.

The staleness flag compares registered plugin entry-point names. It does not detect a plugin update that keeps the same entry-point name or an unrelated conda parser change.

availability is available, not_installed, not_generated, or unavailable. A missing cache includes a hint to run conda completion generate in the target environment. Unknown command paths are rejected as invalid input. The tool is read-only and does not require a safety-policy option.

Raw argv tool#

conda_execute is listed only when the server starts with --allow-exec.

Input	Type	Required	Meaning
`argv`	array of strings	yes	Arguments passed directly after the conda executable
`cwd`	string	no	Working directory for the child process
`stdin`	string	no	Bounded noninteractive standard input
`timeout_seconds`	positive number	no	Shorter timeout for this call, capped by the server limit

The input object rejects unknown fields. The server invokes the executable with an argv list and never invokes a shell.

Capabilities resource#

conda://capabilities is an immutable JSON resource with these top-level fields:

Field	Meaning
`target_executable`	Resolved conda executable path
`conda_version`	Version reported by the target
`catalog`	Complete immutable argparse-derived command catalog and diagnostics
`generated_tools`	Canonical structured tool names
`plugins`	External conda entry-point distributions, versions, values, and detected hooks
`discovery_fingerprint`	Digest used to detect restart-sensitive changes

The resource does not include credentials, authentication objects, request headers, or complete process environments.

Execution result#

Raw and generated tools return the same structured result:

Field	Type	Meaning
`exit_code`	integer or null	Child exit status, or null after a timeout
`stdout`	string	Retained standard output
`stderr`	string	Retained standard error
`duration_ms`	integer	Elapsed execution time in milliseconds
`parsed_json`	any JSON value or null	Stdout parsed only when it is one complete JSON document
`timed_out`	boolean	Whether the configured timeout ended the process
`cancelled`	boolean	Internal cancellation result state, normally false for completed calls
`stdout_truncated`	boolean	Whether standard output exceeded its retained-byte limit
`stderr_truncated`	boolean	Whether standard error exceeded its retained-byte limit
`restart_required`	boolean	Whether the fixed startup catalog should be refreshed

Text content contains a concise summary and a serialized copy of the structured result for clients without structured-content support. A nonzero exit code or timeout marks the MCP tool result as an error. Original output is preserved even when parsed_json is populated. Truncated output is not parsed as JSON.

Errors and cancellation#

Schema errors identify the invalid JSON path without echoing submitted values. Policy errors name the required startup option. Unknown tools and resources do not disclose internal catalog details.

On client cancellation, the server terminates the process tree and propagates request cancellation, so no tool result is returned. On timeout, it terminates the process tree, waits for a bounded grace period, and kills remaining processes if necessary. Conda executions are serialized within one server process.