Adding MCP server tools to a single agent

Edit online

Add an MCP server to an agent and import tools from the server to extend the agent’s capabilities for specific tasks. You can add an MCP server and import tools from existing, local, or remote sources to an agent’s toolset. Use this approach when tools must be available only to a specific agent.

To add an MCP server and import its tools to an agent:

  1. From the navigation menu, click Build.

  2. For IBM Cloud environments, select the workspace that contains the agent.

  3. Click All agents.

  4. Select the agent.

  5. In the Toolset section, click Add tool.

  6. Click MCP server. The Add tools and manage MCP servers window opens.

    You can add an MCP server and import tools in the following ways:

Import tools from an existing MCP server

Import tools from an MCP server that is already configured and available in your environment.

To import tools from an existing MCP server:

  1. Click the Filter icon.

  2. Select the MCP server name and select the tools and click Add to agent.

Before you add a local or remote MCP server

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.

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

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

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

Add a local MCP server and import tools

Add a local MCP server by providing the required configuration, and then import its tools.

To add a local MCP server and import its tools:

  1. Select Add MCP server.

  2. Select Local MCP server and click Next.

  3. Enter the server details, including name, description, and install command.

  4. Optional: Select a connection.

    Local MCP servers use STDIO (standard input/output) for communication. This setting is automatically configured and cannot be changed.

  5. Click Import.

    If the connection is successful, a notification confirms that the MCP server is ready and tools are available.

  6. Click the Filter icon in the search field, and select the MCP server.

  7. Select the tools to add.

Add a remote MCP server and import tools

Add a remote MCP server by establishing a connection, and then import its tools.

To add a remote MCP server and import its tools:

  1. Select Add MCP server.

  2. Select Remote MCP server and click Next.

  3. Enter the server details, including name, description, and server URL.

  4. Select the Transport type:

    • Streamable HTTP: Uses HTTP and streams responses incrementally.

    • Server-Sent Events (SSE): Uses a long-lived connection for real-time updates.

    Streamable HTTP is selected by default.

  5. Optional: Select a connection.

  6. Click Connect.

    If the connection is successful, a notification confirms that the MCP server is ready and tools are available.

  7. Click the Filter icon in the search field, and select the MCP server.

  8. Select the tools to add.