> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing local MCP toolkits

<Note>
  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.
</Note>

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](/tools/toolkits/choosing_tool_type).

## Adding directly from the CLI

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

```bash BASH theme={null}
orchestrate toolkits add
```

<Expandable title="command flags">
  <ResponseField name="--kind (-k)" required>
    The type of toolkit to import. Supports both `mcp` and `python` toolkits. See [Importing Python toolkits](python_toolkits) for more information.
  </ResponseField>

  <ResponseField name="--name (-n)" required>
    The name of the toolkit.
  </ResponseField>

  <ResponseField name="--description" required>
    The description for the toolkit.
  </ResponseField>

  <ResponseField name="--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.
  </ResponseField>

  <ResponseField name="--language (-l)">
    The language used by the package. Supported values: `node` and `python`.
  </ResponseField>

  <ResponseField name="--package_root">
    The root directory of the MCP server package (for mcp servers imported from your local machine).
  </ResponseField>

  <ResponseField name="--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"]'`).
  </ResponseField>

  <ResponseField name="tools">
    A comma-separated list of tools to import, or `*` to import all available tools (e.g. `--tools="tool_1,tool_2"`).
  </ResponseField>

  <ResponseField name="--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](/connections/overview).
  </ResponseField>

  <ResponseField name="--url (-u)">
    The URL of the remote MCP server.
  </ResponseField>

  <ResponseField name="--transport">
    Communication protocol for the remote MCP server. Supported values: `sse` and `streamable_http`.
  </ResponseField>

  <ResponseField name="--tools">
    Comma-separated list of tools to import. Or you can use "\*" to use all tools. (Not supported by Python toolkits)
  </ResponseField>

  <ResponseField name="--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"]'`).
  </ResponseField>

  <ResponseField name="--allowed-context" type="string[]">
    Forwards selected context keys to a remote MCP server.
    Allowed values include <code>tenant\_id</code> and <code>agent\_id</code>. This option applies only to remote MCP
    toolkits.
  </ResponseField>

  <ResponseField name="--tier" type="string">
    Choose a dedicated deployment tier for the python toolkit. Optional for kind 'python'.
  </ResponseField>
</Expandable>

**Examples:**

<Tabs>
  <Tab title="Adding from pypi">
    ```bash BASH theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Importing from npm">
    ```bash BASH theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Local Python">
    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 BASH theme={null}
    ─── mcp_server/
        └── server.py
        └── requirements.txt
    ```

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

    ```bash BASH theme={null}
    # 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"
    ```
  </Tab>

  <Tab title="Local Nodejs">
    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 BASH theme={null}
    # 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"
    ```
  </Tab>
</Tabs>

## 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 BASH theme={null}
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
```

```yaml toolkit_name.yaml theme={null}
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:

<AccordionGroup>
  <Accordion title="Basic Connections">
    * username
    * password
  </Accordion>

  <Accordion title="Bearer Connections">
    * url
    * token
  </Accordion>

  <Accordion title="API Key Connections">
    * url
    * api\_key
  </Accordion>

  <Accordion title="OAuth (Client Credentials)">
    * url
    * access\_token
  </Accordion>

  <Accordion title="OAuth (Auth Code)">
    * url
    * access\_token
  </Accordion>

  <Accordion title="🚧 OAuth (Implicit)">
    **Coming soon**
  </Accordion>

  <Accordion title="OAuth (Password)">
    * url
    * access\_token
  </Accordion>

  <Accordion title="🌐 OAuth (SSO/IDP Flow)">
    * url
    * access\_token
  </Accordion>

  <Accordion title="Key Value Connections">
    * url
    * key1
    * key2
  </Accordion>
</AccordionGroup>

## 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](/tools/toolkits/choosing_tool_type).

## Next steps

* [Choosing a tool type](/tools/toolkits/choosing_tool_type) - Decision guide for selecting the right tool type
* [Importing remote MCP toolkits](/tools/toolkits/remote_mcp_toolkits) - Connect to external MCP servers
* [Importing Python toolkits](/tools/toolkits/python_toolkits) - Bundle Python tools for better performance
* [Managing toolkits](/tools/toolkits/manage_toolkits) - Update and remove toolkits