IBM Wxflows MCP Server Setup and Deployment

Overview

This document describes how to set up, deploy, and run the IBM Wxflows Model Context Protocol (MCP) server included in the examples repository. The MCP server acts as a bridge between MCP-capable clients (for example, Claude Desktop or other MCP clients) and the watsonx.ai Flows Engine (wxflows). It exposes tool definitions and tool-calling behavior over the MCP protocol so developers can invoke external data sources (e.g., Google Books or Wikipedia) from LLM-driven agents and desktop clients.

You will learn how to install the required tools, deploy the Flows Engine project that defines the tools, build the TypeScript MCP server, and run it locally. The guide also explains how to configure MCP clients to use the server and how to debug MCP communication.

Features

• Deploys a wxflows endpoint that exposes tool definitions (google_books, wikipedia).
• MCP TypeScript SDK-based server that speaks MCP over stdio.
• Simple local build and run workflow (npm based).
• Integration-ready for MCP clients (Claude Desktop, custom clients).
• Debugging support via the MCP Inspector script.

Installation / Configuration

Prerequisites

• Node.js (16+) and npm
• wxflows account and CLI authenticated
• Git

Clone the example repository and switch into the example directory:

git clone https://github.com/IBM/wxflows.git
cd wxflows/examples/mcp/javascript

Install the wxflows CLI and authenticate (follow official wxflows docs for exact commands; example shown):

# install (example package name — consult official docs if different)
npm install -g @wxflows/cli

# authenticate your account (interactive)
wxflows login

Deploy the Flows Engine project (this registers the endpoint and tools used by the MCP server):

cd wxflows
wxflows deploy

Create and edit environment variables

# from the example project root
cp .env.sample .env
# then open .env in your editor and set:
# WXFLOWS_APIKEY=<your_wxflows_api_key>
# WXFLOWS_ENDPOINT=<your_wxflows_endpoint>

Install dependencies, build the MCP server, and run locally:

# back in the example app directory
cd ../
npm install
npm run build

# start server directly (stdio MCP)
node build/index.js
# or, if package.json defines a script:
npm start

Tip: The server communicates with MCP clients over stdio. When running directly, it will wait for an MCP client to start and initialize communication.

Available Tools / Resources

This example project pre-defines two tools in the wxflows project:

These tools are deployed to the Flows Engine endpoint during wxflows deploy and are discoverable by MCP clients once the server is running.

Other resources:

• MCP clients: any client implementing the Model Context Protocol can connect (e.g., Claude Desktop).
• MCP Inspector: included as an npm script for inspecting MCP messages and debugging.

Using with an MCP Client (example: Claude Desktop)

Add an MCP server entry to the Claude Desktop configuration file. Example paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Example JSON entry:

{
  "mcpServers": {
    "wxflows-server": {
      "command": "node",
      "args": ["/path/to/wxflows/examples/mcp/javascript/build/index.js"],
      "env": {
        "WXFLOWS_APIKEY": "YOUR_WXFLOWS_APIKEY",
        "WXFLOWS_ENDPOINT": "YOUR_WXFLOWS_ENDPOINT"
      }
    }
  }
}

After updating the config, start Claude Desktop. The client should initialize the MCP connection to your local server and list the google_books and wikipedia tools for use.

Debugging

Because MCP uses stdio streams, debugging can be challenging. This project provides an MCP Inspector helper script:

npm run inspector

The inspector opens a web-based UI or prints a URL, allowing you to watch the MCP JSON messages exchanged between the client and the server and inspect initialization, tool discovery, and tool execution messages.

Use Cases

• Desktop assistant tool-calling: expose internal APIs (search, knowledge bases) to a desktop LLM client so it can fetch facts or perform lookups.
• LangChain/Agent integration: use the MCP server as a local tool provider for agent frameworks that support MCP or stdio-based tool adapters.
• Rapid prototyping: define tools in wxflows and test their behaviour via an MCP client without writing custom protocol code.
• Tool chaining: combine google_books and wikipedia tools to build workflows that pull book metadata and related Wikipedia content for research assistants.

Summary

This example demonstrates how to deploy a wxflows project, build a TypeScript MCP server, and connect MCP-capable clients to call external tools. Follow the install, deploy, and configuration steps above to run the server locally, use the provided tool definitions, and debug interactions using the MCP Inspector. For adding custom tools and deeper integration, consult the wxflows tools documentation and MCP client docs.