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.
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.
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"]').
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:
