Skip to main content
The 2.0 release contains a breaking change renaming what was previously the orchestrate toolkits import command as the orchestrate toolkits add command. A new orchestrate toolkits import command was introduced which operates on files in manner inverse from the orchestrate toolkits export command.
Remote MCP integration lets you connect watsonx Orchestrate to external toolkits hosted on remote servers. Use this setup when your tools live outside your local environment, such as in cloud services or third-party APIs. You can import and manage them using the ADK CLI.

​
Adding remote MCP toolkits using ADK CLI

To import a remote MCP, run the orchestrate toolkits add command with the URL and transport protocol for the MCP server.
BASH
orchestrate toolkits add --kind mcp --name <toolkit-name> --description <toolkit-description>  --url <toolkit-url>  --transport <protocol-for-remote-mcp> --tools <tools>  --app-id <connection>
Examples:
This example connects watsonx Orchestrate to CoinGecko remote MCP server using SSE. For more information, see CoinGecko MCP Server
BASH
orchestrate toolkits add --kind mcp --name coingecko --description "coingecko toolkit"  --url "https://mcp.api.coingecko.com/sse"  --transport "sse" --tools "get_range_coins_market_chart"

​
Importing from a file

You can also 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
transport: streamable_http # streamable_http|sse
server_url: http://my-mcp-server/mcp
tools:
  - *
connections:
  - my_connection

​
Understanding the import process

During import, ADK connects to the remote MCP server to retrieve and validate available tools. ADK checks only the tool schemas for structural correctness and compatibility with watsonx Orchestrate. It doesn’t test tool execution at this stage. watsonx Orchestrate waits up to 30 seconds for the server to respond with the tool list. If the server responds in time, the import continues. If not, the process fails or times out. ADK doesn’t test individual tools during import, so no execution timeouts apply at this stage.

​
Choosing an MCP protocol

ADK supports two transport protocols for MCP: You must choose the transport protocol explicitly. ADK doesn’t support fallback or automatic switching between protocols. Any MCP server that follows the standard protocol and supports SSE or streamable HTTP works without extra configuration. When you use the ADK CLI, Remote MCP supports multiple authentication methods:
  • OAuth2 (without Dynamic Client Registration)
  • API Key
  • Bearer Token
  • Basic Auth
  • Key-value
Note:
  • When connecting to a remote MCP server that uses an API key with a custom name, use the key–value pair method.
  • For OAuth authentication, import the toolkit using Team credentials. To use the tool, you can either switch to Member credentials or continue using Team credentials.
For more information about connections, see Connections.

​
Tracing, tenant and agent context

When Orchestrate calls a remote MCP server through the MCP Gateway, it automatically includes standard tracing information so downstream services can participate in the same request trace for observability and debugging. The tracing context (traceparent and tracestate) is always included and passed in the request metadata. This behavior is built in and requires no configuration. You can also attach correlation identifiers that help with governance, audit logging, and usage attribution. These values are passed as request headers:
  • tenant_id: identifies the customer or tenant
  • agent_id: identifies the calling agent
The following example shows an MCP server definition that includes contextual metadata:
YAML
spec_version: v1
kind: mcp
name: doc-mcp
description: helps you talk to the manager
url: https://developer.watson-orchestrate.ibm.com/mcp
transport: streamable_http
metadata:
    allowed_context:
        - my_context_1
        - my_context_2To
tenant_id and agent_id are not sent by default. You must configure them when you import the remote MCP server or toolkit in the ADK. The tracing context (traceparent, tracestate) is always included and is not configurable.

​
Using SSE protocol

When you use SSE, ADK starts the handshake with a 30-second timeout. This timeout applies during the callback phase of the import. ADK expects only standard SSE headers. The connection setup stays minimal and depends on the server for protocol compliance. ADK doesn’t enforce connection pooling or keep-alive settings. If your server supports them, ADK works with those features. During tool execution testing, you might see End of File (EOF) errors. These usually happen when the server times out or doesn’t respond in time.

​
Using streamable HTTP protocol

When you use streamable HTTP, ADK also starts the handshake with a 30-second timeout. ADK doesn’t expect SSE headers in this case. The setup remains minimal and relies on the server to follow the protocol.

​
Handling import errors

If the server returns an HTTP status code in the 4xx range, the import fails. These errors usually point to invalid requests, authentication issues, or missing resources. Other status codes may trigger warnings, depending on the server’s response. ADK doesn’t distinguish between import-time and runtime execution from the server’s perspective. All responses during import return in JSON format.