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 Agent2from agents.tool import HostedMCPTool34# Initialize the Remote MCP tool5tomtom_mcp = HostedMCPTool(6 url="https://mcp.tomtom.com/maps",7 api_key="YOUR_TOMTOM_API_KEY"8)910# Create an agent with the MCP tool11agent = 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)1617# Run the agent18response = 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 os2from agents import Agent3from agents.tool import HostedMCPTool45# Load API key from environment6tomtom_api_key = os.getenv("TOMTOM_API_KEY")78tomtom_mcp = HostedMCPTool(9 url="https://mcp.tomtom.com/maps",10 api_key=tomtom_api_key11)1213agent = 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)
Example 3: Point of Interest Search
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 coordinates32. Using those coordinates, calculate the driving route to Prague43. Tell me if there are any traffic delays along the route5""")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
| Problem | Possible Fix |
|---|---|
| Connection errors | Verify your API key and URL are correct: https://mcp.tomtom.com/maps. Ensure you have an active internet connection. |
| Import errors | Confirm the OpenAI Agents SDK is properly installed: pip install openai-agents. Try upgrading to the latest version. |
| Authentication errors | Verify 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 limiting | Monitor your API usage on the TomTom Developer Portal. Consider upgrading your plan if you need higher limits. |
Next Steps
- Explore Available Tools: Review the TomTom MCP Available Tools to see all capabilities
- See Examples: Check out Example Use Cases for inspiration
- Learn More about OpenAI Agents: Visit the OpenAI Agents documentation for advanced features
- Understand Pricing: Review TomTom API Pricing for usage costs
- Contribute: Visit the GitHub Repository for source code and contributions