Build a Customer Care Agent with MCP

What you'll build

A customer care agent that connects to a ShopEasy MCP server and answers product availability, order status, and return questions over a chat API.

This tutorial shows how to build an agent that uses an external MCP server through an MCP toolkit. You don't build the MCP server here; you run a provided sample instead. Your job is to connect the agent to it, write the system prompt, and expose a chat endpoint.

The agent receives customer messages over HTTP, reasons about which tool to call, invokes the MCP server, and returns a natural language answer.

Prerequisites

• A model provider for the agent. This tutorial uses the Default WSO2 Model Provider. For other options, see Model providers for LLMs.
• The ShopEasy MCP server running locally. Clone the repo and follow its README to start it: github.com/wso2/integration-samples.

Visual Designer

Step 1: Create and configure the agent

1. Open WSO2 Agent Builder and create or open your project.
2. On the project home page, under Or start from scratch, select Add Agent.
3. In the Add Agent dialog, under Create New, select Create Agent.

4. In the Create Agent form, set:
   • Role to Customer Support Agent.
   • Instructions to:

You are a helpful customer support agent for ShopEasy, an online retailer.
Help customers with product availability, order tracking, and return requests.
Always use the available tools to look up accurate information. Never guess.
Keep responses friendly and concise. Include relevant IDs (order ID, return ID) in your responses.

• Model to Default WSO2 Model Provider.

5. Leave the fields under Advanced Configurations (Maximum Iterations, Verbose, Tool Loading Strategy, Execute Tool Calls In Parallel, and Agent Credential) at their defaults.

Why leave Maximum Iterations at its default?

INFER_TOOL_COUNT resolves to max(number of tools, 10): at least 10 reasoning-action cycles, or more if the agent has more tools available. Once the MCP toolkit is attached in Step 2, this default already gives the agent enough room to reason, call a tool, and respond, without needing a manual override.

6. Set Agent Name to CustomerCareAgent.
7. Select Create Agent.

WSO2 Agent Builder adds the CustomerCareAgent agent under Agents and opens the agent canvas, where the AI Agent node connects to the default WSO2 model provider.

8. Select Add Trigger to the left of the AI Agent node.
9. In the Add Trigger dialog, under Chat Channels, select Agent Chat.
10. Leave Service Path as /customer-care-agent and select Create.

The Agent Chat trigger connects to the AI Agent node, and an AI Agent Services - /customer-care-agent entry point with a chat resource appears under Entry Points. The AI Agent node has a + Add Memory button and an Add Tool button at its bottom-right corner.

Step 2: Add the MCP server as a tool

2.1 Select the tool type

Select Add Tool at the bottom-right corner of the AI Agent node. The Add Tool panel opens, listing Use Connection, Use Function, Use Agent, Use MCP Server, Use Knowledge Base, and Create Custom Tool. Select Use MCP Server.

2.2 Configure the server URL

1. Select Connect Manually. (The other option, WSO2 Agent Manager, lists MCP servers that your organization added to WSO2 Agent Manager.)
2. Set Server Url to http://localhost:8080/mcp.
3. Leave Requires Authentication off.

The panel also shows Tools to Include (defaults to All) and a collapsed Advanced Configurations section. It holds Info (the MCP client identity sent to the server) and HTTP client options such as timeout, redirects, pooling, caching, compression, circuit breaker, retries, and TLS. Leave these at their defaults for this tutorial.

4. Leave Result as the default aiMcpbasetoolkit and select Save.

The MCP toolkit appears as aiMcpbasetoolkit attached to the agent node, connected by a dashed line, and a McpToolKit type is added under Types in the sidebar. The agent discovers the available tools from the server at startup.

Step 3: Run and test

Make sure the ShopEasy MCP server is running, then select Run. WSO2 Agent Builder compiles and starts the service, with progress shown in the integrated terminal.

Once it's running, open the chat resource under Entry Points > AI Agent Services. Its flow shows Start, an agent:run node (with an Open Agent link back to the CustomerCareAgent canvas), and Return. Select Chat in the toolbar (next to Tracing) to open the Agent Chat panel. Type your message in the input field and press Enter to send it.

When the service starts, a pop-up also offers to test it with the Try It client. Selecting Test there opens the same Agent Chat panel.

Try the following messages to exercise all three tools:

• "Do you have any wireless headphones in stock?"
• "What is the status of my order ORD-042?"
• "I want to return ORD-001. The item arrived damaged."

Ballerina Code

connections.bal creates the MCP toolkit:

final McpToolKit aiMcpbasetoolkit = check new ("http://localhost:8080/mcp");

The model provider is initialized inline with ai:getDefaultModelProvider() in agents.bal, so no separate connection is needed for the default WSO2 model provider.

agents.bal defines the agent and the toolkit class:

import ballerina/ai;
import ballerina/mcp;

final ai:Agent CustomerCareAgent = check new (
    systemPrompt = {
        role: string `Customer Support Agent`,
        instructions: string `You are a helpful customer support agent for ShopEasy, an online retailer.
Help customers with product availability, order tracking, and return requests.
Always use the available tools to look up accurate information. Never guess.
Keep responses friendly and concise. Include relevant IDs (order ID, return ID) in your responses.`
    }, model = check ai:getDefaultModelProvider(), tools = [aiMcpbasetoolkit]
);

isolated class McpToolKit {
    *ai:McpBaseToolKit;
    private final mcp:StreamableHttpClient mcpClient;
    private final readonly & ai:ToolConfig[] tools;

    public isolated function init(string serverUrl, mcp:Implementation info = {name: "MCP", version: "1.0.0"},
            *mcp:StreamableHttpClientTransportConfig config) returns ai:Error? {
        do {
            self.mcpClient = check new mcp:StreamableHttpClient(serverUrl, config);
            self.tools = check ai:getPermittedMcpToolConfigs(self.mcpClient, info, self.callTool).cloneReadOnly();
        } on fail error e {
            return error ai:Error("Failed to initialize MCP toolkit", e);
        }
    }

    public isolated function getTools() returns ai:ToolConfig[] => self.tools;

    @ai:AgentTool
    public isolated function callTool(mcp:CallToolParams params) returns mcp:CallToolResult|error {
        return self.mcpClient->callTool(params);
    }
}

main.bal defines the chat service:

import ballerina/ai;
import ballerina/http;

listener ai:Listener agentChatListener = new (listenOn = check http:getDefaultListener());

service /customer\-care\-agent on agentChatListener {
    resource function post chat(@http:Payload ai:ChatReqMessage request)
            returns ai:ChatRespMessage|error {
        string stringResult = check CustomerCareAgent.run(request.message, sessionId = request.sessionId);
        return {message: stringResult};
    }
}

To run and test the agent, follow the same steps in the Visual Designer tab under Step 3: Run and test.

What you built

• Connected an agent to a live MCP server through an MCP toolkit
• Let the agent discover three tools (searchProducts, getOrderStatus, submitReturnRequest) at startup, with no hardcoded tool definitions
• Exposed the agent as an HTTP chat service with session-scoped memory

What's next

• Exposing a service as an MCP server — Build your own MCP server like the one used in this tutorial
• Consuming MCP from an agent — Reference for the MCP toolkit options
• Adding memory to an agent — Persist conversation history across sessions
• AI agent observability — Trace tool calls and monitor agent performance