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. When to use remote MCP toolkits:
  • Tools must run on external infrastructure (cloud services, third-party APIs)
  • You need centralized tool management across multiple Orchestrate instances
  • You have existing remote MCP servers to integrate
  • Tools require specialized infrastructure not available in Orchestrate
Performance characteristics:
  • Network latency added to each tool call (typically 50-200ms)
  • No local resource consumption in Orchestrate
  • Scaling depends on your remote server infrastructure
Tradeoffs:
  • Pros: Centralized updates, external infrastructure, no local resource limits
  • Cons: Network latency, requires external hosting, more complex deployment
For help choosing between remote MCP toolkits, local MCP toolkits, Python toolkits, and standalone Python tools, see Choosing a tool type.

​
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.

​
Comparing remote MCP toolkits with other options

Remote MCP vs Local MCP:
  • Use remote MCP when tools must run on external infrastructure or cloud services
  • Use local MCP when tools can run inside Orchestrate and you want to avoid network latency
Remote MCP vs Python toolkits:
  • Use remote MCP when you need external infrastructure or want centralized tool management
  • Use Python toolkits for better performance with Python tools running inside Orchestrate (no network latency)
Remote MCP vs OpenAPI tools:
  • Use remote MCP when you need MCP protocol features (resources, prompts, streaming)
  • Use OpenAPI tools for simple REST API integrations without MCP protocol overhead
For detailed comparison and decision guidance, see Choosing a tool type.

​
Next steps

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.