smolagents-setup.md

Smolagents Integration Guide

This guide explains how to configure smolagents to the TomTom Maps 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+
• 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:

   # 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
   )

2. Run python3 smolagents_example.py

Setup: Option 2 - Using HTTP Mode (Recommended)

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

1. Install the required package for HTTP mode:

   pip install 'smolagents[mcp]'

2. Run TomTom Maps MCP in HTTP mode using Docker:

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

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

   from 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>"}, 
        "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)

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)