MCP servers

You can import external tools from Model Context Protocol (MCP) servers and add them to your agents to enhance the agent’s ability to accomplish tasks.

About MCP servers

MCP is a standard that allows agents to securely and flexibly interact with external tools and data sources through MCP servers. MCP enables agents to discover, connect to, and start external tools that are provided by MCP servers. These servers function as intermediaries, presenting various capabilities (such as searching web, querying a database, sending email, or fetching web content) in a standardized manner. This process does not require creating custom APIs or manually setting up connections, making it a simpler and more efficient method for agents to use external tools.

With MCP, agents can discover and use these external tools during run time, enhancing their capabilities beyond their inherent features. All interactions with external tools are managed through a single protocol, which simplifies connections and improves efficiency. Moreover, MCP facilitates collaboration and tool sharing among agents from different vendors or platforms.

Tools can be imported from either a local MCP server or a remote MCP server. watsonx Orchestrate allows the installation and execution of Node and Python MCP servers, typically servers that use the npx and uvx commands.

A local MCP server can be installed and run on your own system or network. Typically, it can be downloaded from GitHub repositories and run them on your system. A remote MCP server is hosted on an external server and is accessible over the internet.

MCP supports multiple authentication types, including OAuth 2.0, Bearer Token, API Key, and Basic Authentication, as well as SSO or OBO flows. You can select the required authentication type on the Connections page when configuring an MCP server. For more information about authentication and connection see, Managing app connections and credentials.

Follow these steps before you import tools from a local or remote MCP server:

  1. Identify a local MCP or remote MCP server to use.

    For local MCP server:

    1. Find the local MCP server that you plan to use. Usually, local MCP servers are found on GitHub repositories, such as https://github.com/appcypher/awesome-mcp-servers and https://github.com/modelcontextprotocol/servers.
    2. Locate the installation instructions in the local MCP server documentation or readme file.
    • Typically, you can find instructions about how to start the local MCP server by using Node or Python. For example, npx -y time-mcp.
    • Certain local MCP servers require API keys or other environment variables to be set for communicating with remote services. For example, a "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>" API key.
    1. Ensure that the tools have a description. Each tool in the local MCP server must include a description. The description helps the underlying language model to understand the tool’s purpose and how it is used. The description is also required for successfully importing the tool into watsonx Orchestrate. Missing tool descriptions result in errors.

  2. Ensure that the MCP server is legitimate and safe for your agents to use.

Installing an MCP server that requires environment variables

To install MCP servers that require environment variables, you must add the required variables into an AppID/Connection by using key-value pairs. For example, to use the "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>" API key, you must add a key-value pair with GITHUB_PERSONAL_ACCESS_TOKEN as the key and your personal token as the value.

MCP servers fetch the environment variables when they start, so it is important to set the variables before you import or start an MCP server.

Adding MCP servers

You can add MCP servers directly in IBM watsonx Orchestrate or using the Agent Development Kit (ADK).

To import MCP servers, see Importing tools from an MCP server.

If using the ADK, MCP servers are imported as a toolkit. To learn more, see Managing toolkits.

Limitations

The following features are not supported in MCP server integration:

  • Refreshing or updating the tool list

Tools that are imported from an MCP server cannot be refreshed or updated automatically in the tenant catalog. Any changes to the server-side tool list require reimporting tools manually.

  • OAuth 2.1 and Dynamic Client Registration

OAuth 2.1 and DCR are not supported. Only existing connection types OAuth 2.0, API Key, Basic, Bearer Token, and SSO or OBO are supported.

  • Cancelling tool execution

Once a tool starts running, it must complete automatically. Users cannot stop or cancel the execution.

  • Importing MCP server resources and prompts

Resources like pre-defined prompts or server-side assets cannot be imported and used in the flow builder. Only the tools can be added.

  • Docker images

Dockerized MCP server instances are not supported for import or execution within flow builder.

  • Elicitation and annotation

Elicitation is the process of interactively gathering information from users during tool execution to refine inputs or guide decision-making. Annotation is the process of adding metadata, labels, or comments to tool outputs for further analysis or integration. Tools do not support elicitation and annotation.

  • Importing from an MCP server

    You can import external tools from Model Context Protocol (MCP) servers and add them to your agents to enhance the agent’s ability to accomplish tasks.