Importing local MCP toolkits - IBM watsonx Orchestrate ADK

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.

Local MCP toolkits run MCP servers inside the watsonx Orchestrate runtime using the stdio transport. They support both Python and Node.js implementations and can be imported from npm, PyPI, or your local filesystem. When to use local MCP toolkits:

You have existing MCP servers you want to reuse
You need Node.js for tool development
You want MCP protocol features (resources, prompts, etc.)
You want to share tools across multiple AI platforms

Performance characteristics:

Similar to standalone Python tools with process-per-invocation model
Process startup overhead of approximately 100-300ms per call
Suitable for moderate-frequency tool calls

For help choosing between local MCP toolkits, remote MCP toolkits, Python toolkits, and standalone Python tools, see Choosing a tool type.

Adding directly from the CLI

Use the orchestrate toolkits add command to add a local MCP toolkit into your environment.

BASH

orchestrate toolkits add

Show command flags

--kind (-k)

required

The type of toolkit to import. Supports both mcp and python toolkits. See Importing Python toolkits for more information.

--name (-n)

required

The name of the toolkit.

--description

required

The description for the toolkit.

--package

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)

The language used by the package. Supported values: node and python.

--package_root

The root directory of the MCP server package (for mcp servers imported from your local machine).

--command

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

A comma-separated list of tools to import, or * to import all available tools (e.g. --tools="tool_1,tool_2").

--app-id

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.

--url (-u)

The URL of the remote MCP server.

--transport

Communication protocol for the remote MCP server. Supported values: sse and streamable_http.

--tools

Comma-separated list of tools to import. Or you can use ”*” to use all tools. (Not supported by Python toolkits)

--command

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

--allowed-context

string[]

Forwards selected context keys to a remote MCP server. Allowed values include tenant_id and agent_id. This option applies only to remote MCP toolkits.

--tier

string

Choose a dedicated deployment tier for the python toolkit. Optional for kind ‘python’.

Examples:

Adding from pypi
Importing from npm
Local Python
Local Nodejs

BASH

# 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 mcp-tavily@0.1.10" \
  --tools "*"  \
  --app-id tavily

BASH

# 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 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:

BASH

─── mcp_server/
    └── server.py
    └── requirements.txt

This setup ensures watsonx Orchestrate can correctly install dependencies and run your MCP server during tool execution.

BASH

# 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 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:

my-mcp-server/
├── package.json
├── index.js
└── other-files/

The package.json should include:

Required dependencies
A start script or equivalent command to launch the MCP server

BASH

# 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

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

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.

Supported connection types for local MCP servers

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:

Basic Connections

username
password

Bearer Connections

url
token

API Key Connections

url
api_key

OAuth (Client Credentials)

url
access_token

OAuth (Auth Code)

url
access_token

🚧 OAuth (Implicit)

Coming soon

OAuth (Password)

url
access_token

🌐 OAuth (SSO/IDP Flow)

url
access_token

Key Value Connections

url
key1
key2

Comparing local MCP toolkits with other options

Local MCP vs Python toolkits:

Use local MCP when you need Node.js or MCP-specific features
Use Python toolkits for better performance with frequently called Python tools (no process overhead)

Local MCP vs Remote MCP:

Use local MCP when tools run inside Orchestrate infrastructure
Use remote MCP when tools must run on external infrastructure or cloud services

Local MCP vs Standalone Python tools:

Use local MCP when you need Node.js or want to reuse existing MCP servers
Use standalone Python tools for simpler Python-only tools without MCP protocol needs

For detailed comparison and decision guidance, see Choosing a tool type.

Next steps

Choosing a tool type - Decision guide for selecting the right tool type
Importing remote MCP toolkits - Connect to external MCP servers
Importing Python toolkits - Bundle Python tools for better performance
Managing toolkits - Update and remove toolkits

​Adding directly from the CLI

​Importing from a file

​Supported connection types for local MCP servers

​Comparing local MCP toolkits with other options

​Next steps

Adding directly from the CLI

Importing from a file

Supported connection types for local MCP servers

Comparing local MCP toolkits with other options

Next steps