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.Adding directly from the CLI
Use theorchestrate toolkits add command to add a local MCP toolkit into your environment.
Copy
Ask AI
orchestrate toolkits add
Show command flags
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. Only key_value connections are supported. Each key and value within the connection will be exposed as environment variables to the mcp server. For more information, see Connections. |
- Adding from pypi
- Importing from npm
- Local Python
- Local Nodejs
BASH
Copy
Ask AI
# Setup connection if not already set
orchestrate connections add -a tavily
for 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 use
orchestrate toolkits add --kind mcp \
--name tavily \
--description "Search the internet" \
--command "pipx -y [email protected]" \
--tools "*" \
--app-id tavily
BASH
Copy
Ask AI
# Setup connection if not already set
orchestrate connections add -a tavily
for 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
orchestrate toolkits add --kind mcp \
--name tavily \
--description "Search the internet" \
--command "npx -y [email protected]" \
--tools "*" \
--app-id tavily
When building a Python-based MCP server locally, place a This setup ensures watsonx Orchestrate can correctly install dependencies and run your MCP server during tool execution.
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:BASH
Copy
Ask AI
─── mcp_server/
└── server.py
└── requirements.txt
BASH
Copy
Ask AI
# Setup connection if not already set
orchestrate connections add -a my_connection
for 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 toolkit
orchestrate 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 The
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:Copy
Ask AI
my-mcp-server/
├── package.json
├── index.js
└── other-files/
package.json should include:- Required dependencies
- A
startscript or equivalent command to launch the MCP server
BASH
Copy
Ask AI
# Setup connection if not already set
orchestrate connections add -a my_connection
for 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 toolkit
orchestrate toolkits add \
--kind mcp \
--name toolkit_name \
--description "does something innovative" \
--package-root ./mcp_server \
--command "node server.js" \
--tools "*" \
--app-id "my_connection"
Importing from a file
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
Copy
Ask AI
orchestrate connections add -a my_connection
for 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
orchestrate toolkits import -f toolkit_name.yaml -a my_connection
toolkit_name.yaml
Copy
Ask AI
spec_version: v1
kind: mcp
name: toolkit_name
command: uvx ibm-watsonx-orchestrate-mcp-server
env: []
tools:
- *
connections:
- my_connection
package_root: ./my_toolkit_folder # <-- This is the folder containing your mcp server. The path is relative to this file.