Smolagents Integration Guide

This guide explains how to configure smolagents to the TomTom MCP Server for location-based queries. Keep in mind the size of the models you're using for inference before running this locally.

Prerequisites

• Node.js 22+ (For STDIO)
• Docker Setup Required (For HTTP)
• Python 3.10+
• A valid TomTom API key
• Smolagents installed (pip install smolagents[toolkit])
• Hugging Face User Access Token available

Setup: Option 1 - Using Stdio Mode

1. Personalize the configuration from line 36 to line 41 in smolagents_example.py:

   Copy# Run server with node server_parameters = StdioServerParameters( command="npx", args=["-y", "@tomtom-org/tomtom-mcp@latest"], env={ "TOMTOM_API_KEY": "<your_API_KEY>"}, # replace with your TomTom API key )

   1# Run server with node
   2server_parameters = StdioServerParameters(
   3    command="npx", 
   4    args=["-y", "@tomtom-org/tomtom-mcp@latest"], 
   5    env={
   6        "TOMTOM_API_KEY": "<your_API_KEY>"}, # replace with your TomTom API key
   7)

2. Run python3 smolagents_example.py

Setup: Option 2 - Using HTTP Mode (Recommended)

This approach allows you to run the TomTom MCP server independently from your smolagents code, offering better stability and flexibility.

1. Install the required package for HTTP mode:

   Copypip install 'smolagents[mcp]'

   pip install 'smolagents[mcp]'

2. Run TomTom MCP in HTTP mode using Docker:

   Copy# Run using Docker in the background docker run -d -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest # Or with Docker Compose (after cloning the repository) docker compose up -d

   1# Run using Docker in the background
   2docker run -d -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest
   3
   4# Or with Docker Compose (after cloning the repository)
   5docker compose up -d

3. Create a Python script to connect to the HTTP server:

   Copyfrom smolagents import ToolCollection # Connect to the MCP server running on localhost:3000 with ToolCollection.from_mcp( {"url": "http://localhost:3000/mcp", "headers": {"tomtom-api-key": "your_api_key_here"}, "transport": "streamable-http"}, trust_remote_code=True ) as collection: # List all available tools for tool in collection.tools: print(tool.name) # Use the tools in your agent # Example: Use geocoding # result = collection.tools_dict["tomtom-geocode"].call({"query": "Amsterdam Central Station"}) # print(result)

   1from smolagents import ToolCollection
   2
   3# Connect to the MCP server running on localhost:3000
   4with ToolCollection.from_mcp(
   5    {"url": "http://localhost:3000/mcp", 
   6     "headers": {"tomtom-api-key": "your_api_key_here"}, 
   7     "transport": "streamable-http"}, 
   8    trust_remote_code=True
   9) as collection:
   10    # List all available tools
   11    for tool in collection.tools:
   12        print(tool.name)
   13        
   14    # Use the tools in your agent
   15    # Example: Use geocoding
   16    # result = collection.tools_dict["tomtom-geocode"].call({"query": "Amsterdam Central Station"})
   17    # print(result)

4. Run your Python script.

If configured correctly, the MCP server will fetch results from TomTom APIs.

Troubleshooting

• Ensure TOMTOM_API_KEY is valid and active
• Check that the MCP server is accessible locally
• When using HTTP mode, verify your connection URL and port are correct
• When using Docker, make sure the container is running with docker ps
• Ensure that you have access to the smolagents (most models require their own key or a huggingface CLI login)