xAgent · Developers
Connect your own tools (MCP)
Give your xAgent your own tools: switch the lights in your office, look up an order, read tomorrow's calendar. You run a small program, an MCP server, on any computer you like. It connects out to XIOT, so you don't need to open ports or have a public address.
Before you start
- An agent in xConsole.
- A computer that stays on while you want the tools to work, with Python 3.10 or later.
- The agent's intent setting on Function calling (Configure agent → Models and memory → Intent recognition). It is the default.
1. Copy your agent's MCP address
- In xConsole, open Agents and choose Configure agent on your agent.
- Open the Tools tab. In Your own tools (MCP), press Copy.
The address looks like wss://console.xiot.io/mcp_endpoint/mcp/?token=…. Each agent has its own.
Treat it like a password. Anyone who has it can offer tools to your agent. Don't put it in code you share or commit; keep it in an environment variable.
2. Run the sample calculator
The quickest way to see it work is the open-source calculator sample. It gives your agent one tool: calculator.
git clone https://github.com/78/mcp-calculator
cd mcp-calculator
pip install -r requirements.txt
Set the address you copied, then start it. On macOS or Linux:
export MCP_ENDPOINT='wss://console.xiot.io/mcp_endpoint/mcp/?token=…'
python mcp_pipe.py calculator.py
On Windows (PowerShell):
$env:MCP_ENDPOINT = 'wss://console.xiot.io/mcp_endpoint/mcp/?token=…'
python mcp_pipe.py calculator.py
Leave it running. mcp_pipe.py keeps the connection open and reconnects by itself if the network drops.
3. Check it in xConsole and try it
- Back in the Tools tab, press the refresh button next to the status. It shows Connected · 1 tools and lists
calculator. - Start a new conversation with your xAgent and ask: “What is 18 percent of 2,450?”
New tools are picked up at the start of each conversation, so one that is already running keeps the tools it had.
Write your own tool
A tool is a Python function with a clear name and description. The agent reads the description to decide when to use it. Save this as office.py next to mcp_pipe.py:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Office")
@mcp.tool()
def meeting_room_status(room: str) -> dict:
"""Tells whether a meeting room is free now. room: the room's name, e.g. "Palm"."""
busy = room.lower() in {"palm"} # replace with your booking system
return {"success": True, "result": f"{room} is {'busy' if busy else 'free'} right now"}
if __name__ == "__main__":
mcp.run(transport="stdio")
python mcp_pipe.py office.py
Several MCP servers can connect to the same agent; their tools are added together.
Tips
- Describe when to use it. “Turns the office lights on or off” works better than “lights”. English descriptions work for Arabic conversations too.
- Return short results. The agent turns them into speech, so a sentence beats a table.
- Answer within a few seconds. The person is waiting for a reply.
- Be careful with actions. Check the input, and for anything you can't undo (payments, deleting), have the tool ask for confirmation first.
Troubleshooting
Not connected
- Copy the address again: it must include everything after
token=. - Check the program is still running and its log shows no errors.
- The computer needs outgoing HTTPS (port 443) to
console.xiot.io.
Connected, but the agent doesn't use the tool
- Start a new conversation: tools are loaded when it begins.
- Make the description say clearly what the tool does and when to use it.
- Check Intent recognition is set to Function calling.
MCP, live data or built-in tools?
| Use | When |
|---|---|
| Your own tools (MCP) | The agent should do something or look something up when asked. |
| Live data (context providers) | The agent should already know something at the start of every conversation. |
| Built-in tools | Weather, prayer times, reminders, notes and the device's own controls. Turn them on in Agent → Tools → Edit functions. |