The 2.0 release introduces a breaking change: the former orchestrate toolkits import command has been renamed to orchestrate toolkits add. Additionally, a new orchestrate toolkits import command has been added, which works on files in a way that is the inverse of the orchestrate toolkits export command.
Use the orchestrate toolkits add command to add a local MCP toolkit into your environment.
BASH
orchestrate toolkits add
Show command flags
Flag
Type
Required
Description
--kind / -k
string
Yes
The type of toolkit to import. Only mcp is supported at this time.
--name / -n
string
Yes
The name of the toolkit.
--description
string
Yes
The description for the toolkit.
--package
string
No
NPM or Python package of the MCP server. Runs a npx -y {packagename} or python -m {packagename} command automatically from the package structure. You must provide a --language flag to specify what language it uses.
--language / -l
string
No
The language used by the package. Supported values: node and python.
--package-root
string
No
The root directory of the MCP server package (for mcp servers imported from your local machine).
--command
string
No
The command used to start the MCP server. This can be a string (e.g. 'node dist/index.js --transport stdio') or a JSON-style list (e.g. '["node", "dist/index.js", "--transport", "stdio"]').
--tools / -t
string
No
A comma-separated list of tools to import, or * to import all available tools (e.g. --tools="tool_1,tool_2").
--app-id / -a
string
No
The app_id to of a connection to associate with this toolkit. Each key and value within the connection will be exposed as environment variables to the mcp server. For more information, see Connections.
Examples:
Adding from pypi
Importing from npm
Local Python
Local Nodejs
BASH
# Setup connection if not already setorchestrate connections add -a tavilyfor env in draft live; do orchestrate connections configure -a tavily --env $env --type team --kind key_value orchestrate connections set-credentials -a tavily --env $env -e "TAVILY_API_KEY=$TAVILY_API_KEY"done# Import the toolkit# Note this is a third party mcp server for illustrative purposes only, use the npm variant for production useorchestrate toolkits add --kind mcp \ --name tavily \ --description "Search the internet" \ --command "pipx -y mcp-tavily@0.1.10" \ --tools "*" \ --app-id tavily
BASH
# Setup connection if not already setorchestrate connections add -a tavilyfor env in draft live; do orchestrate connections configure -a tavily --env $env --type team --kind key_value orchestrate connections set-credentials -a tavily --env $env -e "TAVILY_API_KEY=$TAVILY_API_KEY"done# Import the toolkitorchestrate toolkits add --kind mcp \ --name tavily \ --description "Search the internet" \ --command "npx -y tavily-mcp@0.1.3" \ --tools "*" \ --app-id tavily
When building a Python-based MCP server locally, place a requirements.txt file at the root of the folder specified by the --package-root flag. This file should list all required dependencies, and your server script should include the logic to start the MCP server.Here’s a minimal example of the expected folder structure:
This setup ensures watsonx Orchestrate can correctly install dependencies and run your MCP server during tool execution.
BASH
# Setup connection if not already setorchestrate connections add -a my_connectionfor env in draft live; do orchestrate connections configure -a my_connection --env $env --type team --kind key_value orchestrate connections set-credentials -a my_connection --env $env -e "SECURE_ENVIRONMENT_VARIABLE=value"done# Import the toolkitorchestrate toolkits add \ --kind mcp \ --name toolkit_name \ --description "does something innovative" \ --package-root ./mcp_server \ --command "python server.py" \ --tools "*" \ --app-id "my_connection"
When building a Node-based MCP server locally, place a package.json file at the root of the folder specified by the --package-root flag. This file should define your server’s dependencies and the command used to run it.
Here’s a minimal example of the expected folder structure:
It is also possible to import an MCP server configuration from a file. The file contains the same configuration options
used by the add command, within a yaml file, but is easier to integrate with import scripts and CI/CD pipelines.
BASH
orchestrate connections add -a my_connectionfor env in draft live; do orchestrate connections configure -a my_connection --env $env --type team --kind key_value orchestrate connections set-credentials -a my_connection --env $env -e "SECURE_ENVIRONMENT_VARIABLE=value"doneorchestrate toolkits import -f toolkit_name.yaml -a my_connection
toolkit_name.yaml
spec_version: v1kind: mcpname: toolkit_namecommand: uvx ibm-watsonx-orchestrate-mcp-serverenv: []tools: - *connections: - my_connectionpackage_root: ./my_toolkit_folder # <-- This is the folder containing your mcp server. The path is relative to this file.
Local MCP servers can use multiple connection types, and each connection type exposes a specific set of environment variables to the server. These variables allow MCP tools to read the required credentials directly at runtime.
The following environment variables are provided for each connection type:
