Tools and MCP

Tools

Tools are actions that AI agents perform to access data or execute operations. They enable agents to interact with Cumulocity and external systems beyond just generating text responses.

What are tools?

A tool is a function that an agent calls during a conversation to:

• Query device data or measurements.
• Retrieve information from Cumulocity APIs.
• Execute operations or commands.
• Access external services or databases.

When you ask an agent a question that requires data, the agent determines which tools to use, calls them with appropriate parameters, and incorporates the results into its response.

Example conversation:

User: “What is the current temperature of device 12345?”

Agent process:

1. Recognizes it needs device data.
2. Calls the “get device measurements” tool with device ID 12345.
3. Receives the measurement data.
4. Formulates a natural language response: “The current temperature is 23.5°C.”

Using and testing built-in Cumulocity tools

The AI Agent Manager provides default tools for accessing Cumulocity data:

• Device queries: Search and retrieve device information.
• Measurement retrieval: Access current and historical measurements.
• Alarm management: Query alarms and their status.
• Event access: Retrieve events from devices.
• Operation status: Check operation execution status.

These tools are available automatically and require no additional configuration. Test these tools by accessing the Tools section of the AI Agent Manager. Open a tool, which displays the tool’s description and parameters. Enter something into the chat box to test the tool. These tools always use the authorization of the current user and therefore cannot access more data than the user accesses. However, be aware that they change or delete data.

Assigning tools to agents

To enable an agent to use tools:

1. Open the agent configuration.
2. Navigate to the Tools tab.
3. Browse available tools.
4. Select the tools the agent needs.
5. Click Save.

The agent now accesses these tools during conversations when needed.

Best practices

• Tool selection: Assign only the tools an agent actually needs. Too many tools confuse the agent and increase processing time.

• Performance: Tools that take a long time to execute slow down agent responses. Optimize tool performance or use caching where appropriate.

MCP servers

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a standard for connecting AI agents to external tools and data sources. MCP servers expose custom tools that extend agent capabilities beyond the built-in Cumulocity tools.

MCP server characteristics:

• Runs as a separate service accessible via SSE (Server-Sent Events).
• Exposes one or more tools that agents use.
• Defines tool schemas that describe parameters and functionality.
• Executes tool logic and returns results to the agent.

They are therefore perfect fits to extend the capabilities of Cumulocity agents, either by connecting an existing MCP server or by building your own.

Configuring MCP servers

To add an MCP server to the AI Agent Manager:

1. Navigate to Administration > AI Agent Manager.
2. Click Tools in the top menu.
3. Click Configure MCP Server.
4. Enter the URL for your MCP server in the Add a new MCP server field.
5. Click Test connection.
6. If the connection is successful, you see a list of tools the server exposes. Scroll to the bottom of that list, to give the server a name and configure authentication or additional headers.
7. Click Save to persist the configuration and start using it in agents.

The system connects to the MCP server and discovers available tools.

Creating custom MCP servers

To extend the AI Agent Manager with custom tools, develop an MCP server that:

1. Exposes an SSE endpoint.
2. Implements the MCP protocol.
3. Defines tool schemas with clear descriptions.
4. Executes tool logic and returns structured results.

For MCP server implementation details, refer to the Model Context Protocol specification. You can also find an article on how to build MCP servers with NestJS and publish them on the Cumulocity platform as a microservice in the Cumulocity TechCommunity.

Best practices

• Tool naming: Use clear, descriptive names for custom MCP tools. The agent uses tool names and descriptions to decide when to call them.

• Parameter validation: Ensure MCP tools validate parameters and handle errors gracefully. Return clear error messages that help the agent understand what went wrong.