OpenAI Agents SDK

OpenAI Agents SDK Integration Guide

Important note:

The TomTom Remote MCP Server is in public preview.

This guide shows you how to connect your hosted TomTom MCP server to an agent using the OpenAI Agents SDK.

Prerequisites

  • Python 3.10 or higher
  • OpenAI Agents SDK
  • A valid TomTom API key
  • Ensure that your key has access to the MCP Server and the different APIs available through the MCP, e.g. by ticking "All" under "Edit key".

Setup

Step 1: Install the OpenAI Agents SDK

pip install openai-agents

Step 2: Create Your Agent with MCP Connection

1from agents import Agent
2from agents.tool import HostedMCPTool
3
4# Initialize the Remote MCP tool
5tomtom_mcp = HostedMCPTool(
6 url="https://mcp.tomtom.com/maps",
7 api_key="YOUR_TOMTOM_API_KEY"
8)
9
10# Create an agent with the MCP tool
11agent = Agent(
12 name="TomTom Agent",
13 instructions="You are a helpful assistant with access to TomTom location services for geocoding, routing, search, traffic information, and map generation.",
14 tools=[tomtom_mcp]
15)
16
17# Run the agent
18response = agent.run("What's the fastest route from Amsterdam to Berlin?")
19print(response)

For a complete list of available tools and their parameters, see Available Tools.

Step 3: Secure Your API Key

Important: Store your API key in environment variables instead of hardcoding it in your source code:

1import os
2from agents import Agent
3from agents.tool import HostedMCPTool
4
5# Load API key from environment
6tomtom_api_key = os.getenv("TOMTOM_API_KEY")
7
8tomtom_mcp = HostedMCPTool(
9 url="https://mcp.tomtom.com/maps",
10 api_key=tomtom_api_key
11)
12
13agent = Agent(
14 name="TomTom Agent",
15 instructions="You are a helpful assistant with access to TomTom location services.",
16 tools=[tomtom_mcp]
17)

Set the environment variable in your terminal:

Linux/macOS:

export TOMTOM_API_KEY="your_actual_api_key"

Windows (PowerShell):

$env:TOMTOM_API_KEY="your_actual_api_key"

Windows (Command Prompt):

set TOMTOM_API_KEY=your_actual_api_key

Example Usage

Here are some examples of how to use the agent with TomTom MCP:

Example 1: Geocoding

response = agent.run("What are the coordinates of De Ruijterkade 154 in Amsterdam?")
print(response)

Example 2: Route Planning

response = agent.run("Find the fastest route from Amsterdam to Rotterdam and tell me the distance and travel time.")
print(response)
response = agent.run("Find restaurants within 500 meters of coordinates 52.3676, 4.9041")
print(response)

Example 4: Traffic Information

response = agent.run("Are there any traffic incidents in Amsterdam?")
print(response)

Example 5: Complex Multi-Step Query

1response = agent.run("""
21. Geocode 'Alexanderstraße 36, Berlin' to get its coordinates
32. Using those coordinates, calculate the driving route to Prague
43. Tell me if there are any traffic delays along the route
5""")
6print(response)

Local Setup Option

If you need to run the MCP server locally instead of using the remote hosted version, refer to the GitHub repository for installation instructions.

Authentication & Charging

All API calls through the TomTom MCP Server count towards your API usage and are charged according to TomTom's standard pricing.

Learn more: https://developer.tomtom.com/pricing

Troubleshooting

ProblemPossible Fix
Connection errorsVerify your API key and URL are correct: https://mcp.tomtom.com/maps. Ensure you have an active internet connection.
Import errorsConfirm the OpenAI Agents SDK is properly installed: pip install openai-agents. Try upgrading to the latest version.
Authentication errorsVerify your TomTom API key is set correctly passed in the tomtom-api-key header and the API key has access to all relevant API products.
API rate limitingMonitor your API usage on the TomTom Developer Portal. Consider upgrading your plan if you need higher limits.

Next Steps

Additional Resources