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.

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.

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