# How to integrate Here MCP with Pydantic AI

```json
{
  "title": "How to integrate Here MCP with Pydantic AI",
  "toolkit": "Here",
  "toolkit_slug": "here",
  "framework": "Pydantic AI",
  "framework_slug": "pydantic-ai",
  "url": "https://composio.dev/toolkits/here/framework/pydantic-ai",
  "markdown_url": "https://composio.dev/toolkits/here/framework/pydantic-ai.md",
  "updated_at": "2026-05-12T10:14:50.618Z"
}
```

## Introduction

This guide walks you through connecting Here to Pydantic AI using the Composio tool router. By the end, you'll have a working Here agent that can find coffee shops near central park, get driving route for delivery truck, convert address to latitude and longitude through natural language commands.
This guide will help you understand how to give your Pydantic AI agent real control over a Here account through Composio's Here MCP server.
Before we dive in, let's take a quick look at the key ideas and tools involved.

## Also integrate Here with

- [ChatGPT](https://composio.dev/toolkits/here/framework/chatgpt)
- [OpenAI Agents SDK](https://composio.dev/toolkits/here/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/here/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/here/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/here/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/here/framework/codex)
- [Cursor](https://composio.dev/toolkits/here/framework/cursor)
- [VS Code](https://composio.dev/toolkits/here/framework/vscode)
- [OpenCode](https://composio.dev/toolkits/here/framework/opencode)
- [OpenClaw](https://composio.dev/toolkits/here/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/here/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/here/framework/cli)
- [Google ADK](https://composio.dev/toolkits/here/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/here/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/here/framework/ai-sdk)
- [Mastra AI](https://composio.dev/toolkits/here/framework/mastra-ai)
- [LlamaIndex](https://composio.dev/toolkits/here/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/here/framework/crew-ai)

## TL;DR

Here's what you'll learn:
- How to set up your Composio API key and User ID
- How to create a Composio Tool Router session for Here
- How to attach an MCP Server to a Pydantic AI agent
- How to stream responses and maintain chat history
- How to build a simple REPL-style chat interface to test your Here workflows

## What is Pydantic AI?

Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications.
Key features include:
- Type Safety: Built on Pydantic for automatic data validation
- MCP Support: Native support for Model Context Protocol servers
- Streaming: Built-in support for streaming responses
- Async First: Designed for async/await patterns

## What is the Here MCP server, and what's possible with it?

The Here MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Here account. It provides structured and secure access to powerful location, mapping, and geocoding services, so your agent can perform actions like searching places, calculating routes, fetching map imagery, and converting addresses or coordinates on your behalf.
- Smart place discovery and suggestions: Ask your agent to find points of interest, get autosuggested places based on partial queries, or discover addresses near a location.
- Geocoding and reverse geocoding: Convert addresses to geographic coordinates or vice versa, enabling seamless location lookup and mapping in your workflows.
- Map tile and imagery retrieval: Direct your agent to fetch satellite, base, or hybrid map tiles for specific locations, zoom levels, and formats for rich visual context.
- Advanced routing and fleet planning: Have your agent calculate optimized routes with vehicle profiles, constraints, and even isolines for reachable areas based on time or distance.
- Nearby search and contextual browsing: Let your agent browse or search for places around a given location, filtered by categories or names, to surface relevant local information.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `HERE_AUTOSUGGEST` | Autosuggest Places | Tool to fetch possible completions for a partial search term. Use after capturing a partial query and location context to generate typeahead suggestions. |
| `HERE_BROWSE` | Browse Places | Tool to search for places around a given location with optional filters. Use when you need nearby points of interest filtered by categories, food types, or name. |
| `HERE_CALCULATE_ROUTE` | Calculate Fleet Telematics Route | Calculate optimal routes between multiple waypoints supporting various transport modes (car, truck, bicycle, pedestrian). Returns route summary with travel time and distance. Supports fleet-specific parameters like fuel type and preferred routes. Uses HERE Fleet Telematics API with automatic fallback to Routing v8 API. |
| `HERE_CANCEL_PROBLEM` | Cancel Tour Planning Problem | Tool to cancel a running asynchronous tour planning optimization job. Use when you need to stop an in-progress optimization calculation that is no longer needed or was submitted in error. |
| `HERE_COORDINATES_TO_TILE_INDICES` | Coordinates to Tile Indices | Tool to convert geographic coordinates to Web Mercator XYZ tile indices. Use when mapping a lat/lng to its containing tile at a given zoom level. |
| `HERE_DECODE_ROUTE_HANDLE` | Decode Route Handle | Tool to decode and return a route from a previously calculated route handle via POST request. Use when you need to retrieve a route using a handle obtained from a previous route calculation. |
| `HERE_DISCOVER` | Discover Places | Tool to discover places and addresses by free-form text near a location. Use when you need to find points of interest or specific addresses from a natural-language query. |
| `HERE_FIND_SEQUENCE` | Solve Vehicle Routing Problem | Tool to solve a Vehicle Routing Problem (VRP) by optimizing routes for a fleet of vehicles serving multiple jobs. Use when you need to optimize delivery routes, pickup sequences, or multi-stop journeys with vehicle capacity constraints. This is a preview feature and subject to change. |
| `HERE_FIND_WAYPOINT_SEQUENCE` | Find Optimal Waypoint Sequence | Tool to find the optimal sequence of waypoints using POST request to solve the Travelling Salesman Problem. Supports advanced vehicle parameters including truck restrictions, hazardous goods, toll calculations, and environmental zones. Returns optimized visit order with distance, time, and interconnections between waypoints. |
| `HERE_GEOCODE` | Geocode Address | Tool to convert structured address data into geographic coordinates. Use when you need precise lat/lng from a free-text or qualified address input. |
| `HERE_GET_ALIASES_HEALTH` | Get Aliases Service Health | Tool to check the health status of the HERE Tracking aliases service. Use to verify service availability before making other aliases API calls. |
| `HERE_GET_ALIASES_VERSION` | Get Aliases Service Version | Tool to get the current version of the HERE Tracking Aliases service. Use when you need to verify the service version for compatibility or debugging purposes. |
| `HERE_GET_ASSOCIATIONS_HEALTH` | Get Associations Service Health | Tool to check the health status of the HERE Tracking Associations API service. Use when you need to verify that the associations service is operational and responding correctly. |
| `HERE_GET_ASSOCIATIONS_VERSION` | Get Associations Service Version | Tool to retrieve the current version of the HERE Associations tracking service. Use when you need to verify the service version or check service availability. |
| `HERE_GET_AUTOCOMPLETE` | Get Address Autocomplete | Tool to get address autocomplete suggestions for partial address queries. Use when you need address-specific completions focusing on addresses and administrative areas, unlike autosuggest which includes broader place categories. |
| `HERE_GET_BASE_MAP_TILE` | Get Base Map Tile | Retrieves a base map tile image from HERE Raster Tile API v3. Returns map tiles in various styles (normal day/night, satellite, reduced/lite) at specified zoom levels and tile coordinates using the Web Mercator projection. Tiles are provided in 256x256 or 512x512 pixel sizes in PNG or JPEG format. Use this to display map imagery in applications requiring tiled map rendering. |
| `HERE_GET_BULKJOBS_HEALTH` | Get Bulkjobs Service Health | Tool to check the health status of the HERE Tracking bulkjobs service. Use to verify service availability before making other bulkjobs API calls. |
| `HERE_GET_BULKJOBS_VERSION` | Get Bulkjobs Service Version | Tool to retrieve the current version of the HERE Bulkjobs tracking service. Use when you need to verify the service version number. |
| `HERE_GET_C2_C_HEALTH` | Get C2C Service Health | Tool to check HERE C2C service health status. Use when you need to verify if the Car-to-Cloud tracking service is operational. |
| `HERE_GET_C2_C_VERSION` | Get C2C Service Version | Tool to get the current version of the HERE C2C tracking service. Use when you need to check the service version for compatibility or monitoring purposes. |
| `HERE_GET_COPYRIGHT` | Get Copyright | Tool to retrieve copyright information for HERE map tiles. Returns copyright text, labels, and geographic coverage areas for different map styles and zoom levels. Use when you need to display proper attribution for HERE map tiles in your application. |
| `HERE_GET_DEPARTURES` | Get Transit Departures | Tool to get next departures from transit stations. Returns upcoming departures with line information, destination, and real-time delays. Use when you need to find public transit departure times either by station ID or by geographic location. |
| `HERE_GET_EVENTS_HEALTH` | Get Events Health Status | Tool to check the health status of the HERE Events API service. Use to verify if the Events API is operational. |
| `HERE_GET_EVENTS_VERSION` | Get Events Service Version | Tool to get the current version of the HERE Events service. Use when you need to check the service version for compatibility or monitoring purposes. |
| `HERE_GET_FEATURES` | Get Features | Tool to retrieve available map features per style for tile rendering. Use when you need to discover which features (environmental zones, congestion zones, POIs, vehicle restrictions) are supported by different map styles. |
| `HERE_GET_GEOFENCES_HEALTH` | Get Geofences Health | Tool to check the health status of the HERE Geofences service. Use when you need to verify if the geofences API is operational before making other requests. |
| `HERE_GET_GEOFENCES_VERSION` | Get Geofences Service Version | Tool to get the current version of the HERE Geofences service. Use when you need to check the service version for compatibility or monitoring purposes. |
| `HERE_GET_HEALTH` | Get Service Health Status | Tool to check the health status of the HERE Tracking API service. Use when you need to verify if the service is operational and performing as expected. |
| `HERE_GET_INCIDENTS_BY_ID` | Get Incident By ID | Tool to get details of a specific traffic incident by its ID. Returns full incident information including description, severity, and affected road segments. Use when you need comprehensive details about a known traffic incident. |
| `HERE_GET_INFO` | Get Raster Tile API Info | Tool to get metadata about the HERE Raster Tile API v3. Returns information about accepted values of API parameters including supported image formats, sizes, styles, projections, resources, and zoom level ranges. Use when you need to discover available options before requesting map tiles. |
| `HERE_GET_ISOLINES` | Get Isolines | Tool to calculate isolines. Use when you need reachable area polygons based on time, distance, or consumption ranges. |
| `HERE_GET_LABELS_HEALTH` | Get Labels Service Health | Tool to check the health status of the HERE Labels service. Use when you need to verify if the labels service is operational. |
| `HERE_GET_LABELS_VERSION` | Get Labels Service Version | Tool to retrieve the current version of the HERE Labels service. Use when you need to check the service version for compatibility or debugging purposes. |
| `HERE_GET_LABEL_TILE` | Get Label Tile | Retrieves a map tile image with text labels using HERE Raster Tile API v3. Returns map tiles in various styles (day/night, grayscale, terrain) with street names, city names, and POI labels rendered in specified language(s). Use this when you need labeled map imagery at specific tile coordinates and zoom levels for tiled map rendering. Tiles use Web Mercator projection in standard 256x256 or 512x512 pixel sizes. |
| `HERE_GET_LANGUAGES` | Get Supported Languages | Tool to retrieve supported languages for map tile labels from HERE Raster Tile API. Use when you need to determine which language options are available for rendering map labels and text on different map layers. |
| `HERE_GET_LARGEDATA_HEALTH` | Get Largedata Service Health | Tool to check the health status of the HERE Tracking largedata service. Use to verify service availability before making other largedata API calls. |
| `HERE_GET_LARGEDATA_VERSION` | Get Largedata Service Version | Tool to retrieve the current version of the HERE largedata tracking service. Use when you need to verify the service version number. |
| `HERE_GET_LOCATIONS_HEALTH` | Get Locations Service Health | Tool to check the health status of HERE's locations tracking service. Use when you need to verify if the locations API is operational and responding correctly. |
| `HERE_GET_LOCATIONS_VERSION` | Get Locations Service Version | Tool to retrieve the current version of the HERE Tracking Locations service. Use when you need to check the service version or verify service availability. |
| `HERE_GET_MAP_IMAGE` | Get Map Image | Retrieves a static map image from HERE Map Image API v3. Returns a downloadable PNG image with customizable center/zoom, dimensions, style, and overlay markers/shapes. Useful for generating map snapshots for reports, visualizations, or embedding in applications. |
| `HERE_GET_MAP_TILE_TRANSIT` | Get Map Tile with Transit | Tool to request a map tile with public transport overlay from HERE Raster Tile API v3. Use when you need street map tiles with transit information displayed (buses, trains, tram lines, etc.). Returns a PNG image with base map and public transport overlays. |
| `HERE_GET_MATRIX` | Compute Routing Matrix | Computes routing matrices for batch distance and travel time calculations between multiple origins and destinations. Use this tool when you need to: - Calculate distances/times for all combinations of multiple starting points and destinations - Perform batch routing calculations efficiently (up to 10,000 origins × 10,000 destinations) - Get travel times with traffic considerations (when departureTime is provided) - Optimize delivery routes, logistics planning, or proximity analysis The response returns flat arrays in row-major order where element k represents the route from origin i to destination j, calculated as: k = numDestinations * i + j |
| `HERE_GET_MATRIX_MATRIX_ID` | Get Matrix Calculation Result | Tool to retrieve the result of a successfully completed matrix calculation. Use when you have a matrixId from a previous matrix calculation request and need to fetch the computed distances and travel times. |
| `HERE_GET_METADATA_HEALTH` | Get Metadata Service Health | Tool to retrieve the health status of the HERE Tracking metadata service. Use when you need to verify if the service is operational. |
| `HERE_GET_METADATA_VERSION` | Get Service Version | Tool to retrieve the current version number of the HERE Tracking service. Use when you need to verify the service version or check API compatibility. |
| `HERE_GET_NOTIFICATIONS_HEALTH` | Get Notifications Service Health | Tool to check the health status of the HERE Tracking Notifications service. Use when you need to verify if the notifications service is operational and performing as expected. |
| `HERE_GET_NOTIFICATIONS_VERSION` | Get Notifications Service Version | Tool to get the current version of the HERE Notifications service. Use when you need to check the service version for compatibility or monitoring purposes. |
| `HERE_GET_OPENAPI` | Get OpenAPI Specification | Tool to retrieve the OpenAPI 3 specification for the HERE Traffic API v7. Use when you need the complete API schema documentation. |
| `HERE_GET_POLITICAL_VIEWS` | Get Political Views | Tool to retrieve available geopolitical views for HERE map rendering. Returns a mapping of map resources to supported country-specific boundary representations (ISO 3166-1 alpha-2 codes). Use when you need to determine which political views are available for displaying maps with region-specific boundaries. |
| `HERE_GET_PROBLEMS_SOLUTION` | Get Tour Planning Solution | Tool to retrieve the solution for a completed tour planning problem. Returns optimized tours with routes, stops, schedules, and statistics. Use after submitting a problem asynchronously to get the calculated solution. |
| `HERE_GET_PROFILE` | Get Matrix Routing Profile | Tool to retrieve a specific matrix routing profile definition by its ID. Use when you need to inspect predefined routing configurations including transport mode, routing optimization, avoid options, and region definitions. |
| `HERE_GET_PROFILES` | List Matrix Routing Profiles | Tool to list all supported predefined routing profiles for matrix routing calculations. Use when you need to discover available profiles with their transport modes, routing optimizations, and constraints. |
| `HERE_GET_REGISTRY_HEALTH` | Get Registry Health | Tool to check the health status of the HERE Tracking Registry service. Use this to verify if the registry service is operational and responding normally. |
| `HERE_GET_REGISTRY_VERSION` | Get Registry Service Version | Tool to get the current version of the HERE Registry service. Use when you need to check the service version for compatibility or monitoring purposes. |
| `HERE_GET_REPORTS_HEALTH` | Get Service Health Status | Tool to check the HERE Tracking service health status. Use when you need to verify if the service is operational and performing as expected. |
| `HERE_GET_RESOURCE_PROJECTION_ZOOM_COLUMN_ROW_FORMAT` | Get Raster Map Tile | Tool to retrieve a raster map tile image for a specific zoom level, column, and row from HERE Raster Tile API v3. Use when you need to fetch map tiles in various formats (PNG, JPEG) for different resource types (base maps, aerial imagery, traffic overlays, etc.). Supports customization options including language, geopolitical views, styles, and resolution. |
| `HERE_GET_ROUTES` | Calculate Routes | Tool to calculate routes between waypoints supporting multiple transport modes (car, truck, pedestrian, bicycle, scooter, taxi, bus). Returns route geometry, turn-by-turn instructions, travel time, and distance. Use when planning navigation or analyzing travel options. |
| `HERE_GET_RULES_HEALTH` | Get Rules Service Health | Tool to check the health status of the HERE Tracking Rules service. Use when you need to verify if the Rules API service is operational. Returns a simple health status message. |
| `HERE_GET_RULES_VERSION` | Get Rules Service Version | Tool to retrieve the current version of the HERE Tracking Rules service. Use when you need to check the service version for compatibility or debugging purposes. |
| `HERE_GET_SENSORS_HEALTH` | Get Sensors Health | Tool to check the health status of the HERE Tracking Sensors service. Use this to verify that the service is operational and performing as expected. |
| `HERE_GET_SENSORS_VERSION` | Get Sensors Service Version | Tool to retrieve the current version of the HERE Tracking sensors service. Use when you need to check the service version information. |
| `HERE_GET_SHADOWS_HEALTH` | Get Shadows Service Health | Tool to check the health status of the HERE Tracking Shadows service. Use when you need to verify if the shadows service is operational and performing as expected. |
| `HERE_GET_SHADOWS_VERSION` | Get Shadows Service Version | Tool to retrieve the current version of the HERE Shadows tracking service. Use when you need to verify the service version number. |
| `HERE_GET_SHIPMENTS_HEALTH` | Get Shipments Health | Tool to check the health status of the HERE Shipments service. Use when you need to verify if the tracking service is operational. |
| `HERE_GET_SHIPMENTS_VERSION` | Get Shipments Service Version | Tool to get the HERE shipments tracking service version. Use when you need to check the current version of the shipments API service. |
| `HERE_GET_STATIONS` | Get Transit Stations | Tool to search for transit stations around a location. Returns station names, locations, and available transit lines. Use when you need to find public transportation stations within a specific area or by station ID. |
| `HERE_GET_STATUS_STATUS_ID` | Get Tour Planning Job Status | Check the status of an asynchronous tour planning optimization job. Use when you have submitted a tour planning problem and need to poll for completion. Returns the current status ('pending', 'inProgress', 'success', 'timeout', or 'failure'). When completed successfully, provides resource object with problemId and solution URL. |
| `HERE_GET_TIMESTAMP` | Get Server Timestamp | Tool to get the current server timestamp from HERE Tracking API. Use when you need a synchronized Unix epoch timestamp (seconds since 1970-01-01 00:00:00 UTC) from HERE servers. |
| `HERE_GET_TRACES_HEALTH` | Get Traces Service Health | Tool to check the health status of the HERE Tracking service. Use when you need to verify if the traces API is operational and performing as expected. |
| `HERE_GET_TRACES_VERSION` | Get Tracking Service Version | Tool to retrieve the current version of the HERE Tracking service. Use when you need to check the service version for compatibility or diagnostic purposes. |
| `HERE_GET_TRAFFIC_FLOW` | Get Traffic Flow | Tool to retrieve real-time traffic flow data. Use when you need current congestion metrics for a specified area. |
| `HERE_GET_TRAFFIC_INCIDENTS` | Get Traffic Incidents | Tool to fetch real-time traffic incidents within a specified area. Use when you need up-to-date incident data for a geographic region. |
| `HERE_GET_TRAFFIC_TILE` | Get Traffic Tile | Retrieve a traffic flow overlay tile image showing real-time traffic conditions. Returns a PNG image tile that can be overlaid on maps to visualize traffic speed and congestion. Use this when you need to display traffic flow data for a specific geographic area defined by tile coordinates (zoom, x, y). |
| `HERE_GET_USERS_HEALTH` | Get Users Service Health | Tool to check the HERE Tracking Users API service health status. Use this to verify that the service is operational before making other API calls. |
| `HERE_GET_USERS_VERSION` | Get Users Service Version | Tool to get the current version of the HERE tracking service. Use when you need to verify the service version or check service availability. |
| `HERE_GET_VECTOR_TILE` | Get Vector Tile | Retrieves protocol buffer encoded binary vector tiles using HERE Vector Tile API v2. Returns map tiles in OMV (Optimized Map for Visualization) format following the Map Vector Tile open specification. Use this when you need vector tile data at specific tile coordinates and zoom levels for client-side map rendering. Supports layer exclusion and conditional requests via ETags. |
| `HERE_GET_VECTORTILE_DOCS_LAYERS_JSON` | Get Vector Tiles Layers Documentation | Tool to retrieve OMV-2 layers documentation for HERE Vector Tiles. Returns comprehensive schema documentation including layer definitions, geometry types, field names, and possible values in TileJSON 3.0.0 format. Use when you need to understand the data structure of vector tiles before requesting or processing them. |
| `HERE_GET_VECTORTILES_COPYRIGHT` | Get Vector Tiles Copyright | Tool to retrieve copyright information for HERE vector tiles. Returns copyright labels, alt text, zoom level ranges, and bounding boxes for both base and core map layers. Use when you need to display proper copyright attribution for vector tile maps. |
| `HERE_GET_VECTORTILES_INFO` | Get Vector Tiles Info | Tool to retrieve the current map version from HERE Vector Tiles Service. Use when you need the encoded map version identifier, which is valid for 24 hours and must be refreshed after that period. |
| `HERE_GET_VECTORTILES_LANGUAGES` | Get Vector Tiles Languages | Tool to retrieve supported languages for vector map tiles from HERE Vector Tiles API. Use when you need to determine which language options are available for rendering vector map labels and text on different layers (base, core). |
| `HERE_GET_VECTORTILES_OPENAPI` | Get Vector Tiles OpenAPI Specification | Tool to retrieve the OpenAPI specification for the HERE Vector Tiles API v2. Use when you need the complete API schema documentation for vector tile endpoints. |
| `HERE_GET_VECTORTILES_PROTO` | Get Vector Tiles Proto Formats | Tool to retrieve a list of available protocol buffer formats from HERE Vector Tiles Service. Use when you need to discover available proto file formats for subsequent requests. |
| `HERE_GET_VECTORTILES_PROTO_NAME` | Get Vector Tiles Proto File | Tool to retrieve protocol buffer (.proto) file format definitions from HERE Vector Tiles API. Returns the specified .proto file that defines the data structure for vector tiles. Use when you need the protocol buffer schema to parse or understand the binary vector tile format. |
| `HERE_GET_VECTORTILES_PVIEWS` | Get Vector Tiles Political Views | Tool to retrieve available political views for HERE vector tiles. Returns lists of country codes that have disputed territories in base and core map data. Use when you need to determine which political view codes are valid for the 'pview' parameter in tile requests. |
| `HERE_GET_VERSION` | Get Version | Tool to retrieve the version information of the HERE Traffic API. Use when you need to check the current API version or service version. |
| `HERE_GET_WAYPOINT_SEQUENCE` | Get Waypoint Sequence | Optimizes the visit order of multiple waypoints between a fixed origin and destination. Returns the most efficient sequence to visit all intermediate points, minimizing either travel time or distance. Useful for delivery routing, tour planning, and multi-stop journey optimization. |
| `HERE_GET_WEATHER_FORECAST_DAILY` | Daily Weather Forecast | Get 7-day weather forecasts for any location worldwide. Returns either detailed segment-level forecasts (morning/afternoon/evening/night) or simplified daily summaries. Supports location queries by city name, coordinates, or U.S. ZIP codes. Use 'forecast7days' for comprehensive weather planning, 'forecast7daysSimple' for quick daily overview. |
| `HERE_GET_WEATHER_OBSERVATION` | Get Weather Observation | Tool to retrieve current weather observation. Use after determining a specific location to get up-to-date weather conditions. |
| `HERE_IMPORT_ROUTE` | Import Route from Trace | Tool to import and calculate a route from GPS trace points. Accepts a polyline of coordinates and returns routing information including traffic delays, turn-by-turn instructions, and actions. Use when you need to convert a sequence of GPS coordinates into a structured route with navigation details. |
| `HERE_LOCATE_DEVICE` | Locate Device | Determine device location based on WiFi and cellular network measurements. Supports 2G/3G/4G/5G cellular (GSM, WCDMA, TD-SCDMA, LTE, CDMA) and WLAN positioning. Use when you need to locate a device using network infrastructure data instead of GPS. At least one network measurement type must be provided. |
| `HERE_LOOKUP` | Lookup Location by HERE ID | Retrieves comprehensive details for a location using its HERE ID. Returns structured data including address, coordinates, categories, contacts, and references. Use this action when you have a HERE ID from geocoding, search, or discovery actions and need complete information about that specific location. Supports both place IDs and address IDs. |
| `HERE_POST_ROUTES` | Calculate Routes via POST | Calculate routes using POST method with extensive customization options via request body. Supports car, truck, pedestrian, bicycle, scooter, taxi, and bus modes. Use when you need to avoid specific areas/segments, specify EV preferences, or set speed restrictions that exceed URL length limits. |
| `HERE_REVERSE_GEOCODE` | Reverse Geocode Coordinates | Converts geographic coordinates (latitude, longitude) into human-readable addresses and location details. Use this tool when you need to: - Find the street address for a specific GPS coordinate - Identify what place or building is at a location - Get detailed address components (street, city, postal code, country) - Determine timezone information for coordinates Returns structured address data including full labels, administrative divisions, and distance from query point. Supports worldwide coverage with responses in multiple languages. |
| `HERE_SUBMIT_TOUR_PLANNING_PROBLEM` | Submit Tour Planning Problem | Submit a tour planning problem synchronously to solve vehicle routing problems with constraints like time windows, capacity, and vehicle types. Returns optimized tours for the fleet with routes, schedules, and statistics. Use when you need to optimize delivery/pickup routes for multiple vehicles. |
| `HERE_SUBMIT_TOUR_PLANNING_PROBLEM_ASYNC` | Submit Tour Planning Problem (Async) | Submit a tour planning problem asynchronously for large-scale vehicle routing optimization. Returns a status ID to poll for results. Use this for complex problems with multiple vehicles, jobs, and constraints. Supports up to 3000 jobs and 150 vehicle types. |
| `HERE_WEATHER_ALERTS` | Weather Alerts | Retrieve severe weather alerts for specified locations or routes. This tool queries the HERE Weather API to get active weather alerts including severe weather warnings, watches, and advisories. Supports multiple location inputs: - q: Free-text location query (e.g., 'Berlin, Germany', 'New York') - location: Precise coordinates in 'lat,lng' format (e.g., '52.5200,13.4050') - zipCode: US ZIP code (e.g., '10001') Optional parameters: - units: 'metric' or 'imperial' for measurement units - lang: Language code for alert descriptions (e.g., 'en-US', 'de-DE') - politicalView: ISO country code for disputed territory representation Returns alert information including location, severity, type, and time segments when alerts are active. Empty timeSegments list indicates no active alerts. |
| `HERE_WEATHER_ASTRONOMY` | Get Astronomy Forecast | Tool to fetch astronomical data (sunrise, sunset) for a specific location. Use when you need daily sun and moon event times. |
| `HERE_WEATHER_FORECAST_HOURLY` | Hourly Weather Forecast | Tool to fetch hourly weather forecasts. Use when you need up to 48 hours of forecast data for a location. |

## Supported Triggers

None listed.

## Creating MCP Server - Stand-alone vs Composio SDK

The Here MCP server is an implementation of the Model Context Protocol that connects your AI agent to Here. It provides structured and secure access so your agent can perform Here operations on your behalf through a secure, permission-based interface.
With Composio's managed implementation, you don't have to create your own developer app. For production, if you're building an end product, we recommend using your own credentials. The managed server helps you prototype fast and go from 0-1 faster.

## Step-by-step Guide

### 1. Prerequisites

Before starting, make sure you have:
- Python 3.9 or higher
- A Composio account with an active API key
- Basic familiarity with Python and async programming

### 1. Getting API Keys for OpenAI and Composio

OpenAI API Key
- Go to the [OpenAI dashboard](https://platform.openai.com/settings/organization/api-keys) and create an API key. You'll need credits to use the models, or you can connect to another model provider.
- Keep the API key safe.
Composio API Key
- Log in to the [Composio dashboard](https://dashboard.composio.dev?utm_source=toolkits&utm_medium=framework_docs).
- Navigate to your API settings and generate a new API key.
- Store this key securely as you'll need it for authentication.

### 2. Install dependencies

Install the required libraries.
What's happening:
- composio connects your agent to external SaaS tools like Here
- pydantic-ai lets you create structured AI agents with tool support
- python-dotenv loads your environment variables securely from a .env file
```bash
pip install composio pydantic-ai python-dotenv
```

### 3. Set up environment variables

Create a .env file in your project root.
What's happening:
- COMPOSIO_API_KEY authenticates your agent to Composio's API
- USER_ID associates your session with your account for secure tool access
- OPENAI_API_KEY to access OpenAI LLMs
```bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key
```

### 4. Import dependencies

What's happening:
- We load environment variables and import required modules
- Composio manages connections to Here
- MCPServerStreamableHTTP connects to the Here MCP server endpoint
- Agent from Pydantic AI lets you define and run the AI assistant
```python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()
```

### 5. Create a Tool Router Session

What's happening:
- We're creating a Tool Router session that gives your agent access to Here tools
- The create method takes the user ID and specifies which toolkits should be available
- The returned session.mcp.url is the MCP server URL that your agent will use
```python
async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Here
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["here"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")
```

### 6. Initialize the Pydantic AI Agent

What's happening:
- The MCP client connects to the Here endpoint
- The agent uses GPT-5 to interpret user commands and perform Here operations
- The instructions field defines the agent's role and behavior
```python
# Attach the MCP server to a Pydantic AI Agent
here_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
agent = Agent(
    "openai:gpt-5",
    toolsets=[here_mcp],
    instructions=(
        "You are a Here assistant. Use Here tools to help users "
        "with their requests. Ask clarifying questions when needed."
    ),
)
```

### 7. Build the chat interface

What's happening:
- The agent reads input from the terminal and streams its response
- Here API calls happen automatically under the hood
- The model keeps conversation history to maintain context across turns
```python
# Simple REPL with message history
history = []
print("Chat started! Type 'exit' or 'quit' to end.\n")
print("Try asking the agent to help you with Here.\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in {"exit", "quit", "bye"}:
        print("\nGoodbye!")
        break
    if not user_input:
        continue

    print("\nAgent is thinking...\n", flush=True)

    async with agent.run_stream(user_input, message_history=history) as stream_result:
        collected_text = ""
        async for chunk in stream_result.stream_output():
            text_piece = None
            if isinstance(chunk, str):
                text_piece = chunk
            elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                text_piece = chunk.delta
            elif hasattr(chunk, "text"):
                text_piece = chunk.text
            if text_piece:
                collected_text += text_piece
        result = stream_result

    print(f"Agent: {collected_text}\n")
    history = result.all_messages()
```

### 8. Run the application

What's happening:
- The asyncio loop launches the agent and keeps it running until you exit
```python
if __name__ == "__main__":
    asyncio.run(main())
```

## Complete Code

```python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()

async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Here
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["here"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")

    # Attach the MCP server to a Pydantic AI Agent
    here_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[here_mcp],
        instructions=(
            "You are a Here assistant. Use Here tools to help users "
            "with their requests. Ask clarifying questions when needed."
        ),
    )

    # Simple REPL with message history
    history = []
    print("Chat started! Type 'exit' or 'quit' to end.\n")
    print("Try asking the agent to help you with Here.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "bye"}:
            print("\nGoodbye!")
            break
        if not user_input:
            continue

        print("\nAgent is thinking...\n", flush=True)

        async with agent.run_stream(user_input, message_history=history) as stream_result:
            collected_text = ""
            async for chunk in stream_result.stream_output():
                text_piece = None
                if isinstance(chunk, str):
                    text_piece = chunk
                elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                    text_piece = chunk.delta
                elif hasattr(chunk, "text"):
                    text_piece = chunk.text
                if text_piece:
                    collected_text += text_piece
            result = stream_result

        print(f"Agent: {collected_text}\n")
        history = result.all_messages()

if __name__ == "__main__":
    asyncio.run(main())
```

## Conclusion

You've built a Pydantic AI agent that can interact with Here through Composio's Tool Router. With this setup, your agent can perform real Here actions through natural language.
You can extend this further by:
- Adding other toolkits like Gmail, HubSpot, or Salesforce
- Building a web-based chat interface around this agent
- Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Here for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.

## How to build Here MCP Agent with another framework

- [ChatGPT](https://composio.dev/toolkits/here/framework/chatgpt)
- [OpenAI Agents SDK](https://composio.dev/toolkits/here/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/here/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/here/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/here/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/here/framework/codex)
- [Cursor](https://composio.dev/toolkits/here/framework/cursor)
- [VS Code](https://composio.dev/toolkits/here/framework/vscode)
- [OpenCode](https://composio.dev/toolkits/here/framework/opencode)
- [OpenClaw](https://composio.dev/toolkits/here/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/here/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/here/framework/cli)
- [Google ADK](https://composio.dev/toolkits/here/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/here/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/here/framework/ai-sdk)
- [Mastra AI](https://composio.dev/toolkits/here/framework/mastra-ai)
- [LlamaIndex](https://composio.dev/toolkits/here/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/here/framework/crew-ai)

## Related Toolkits

- [Excel](https://composio.dev/toolkits/excel) - Microsoft Excel is a robust spreadsheet application for organizing, analyzing, and visualizing data. It's the go-to tool for calculations, reporting, and flexible data management.
- [21risk](https://composio.dev/toolkits/_21risk) - 21RISK is a web app built for easy checklist, audit, and compliance management. It streamlines risk processes so teams can focus on what matters.
- [Abstract](https://composio.dev/toolkits/abstract) - Abstract provides a suite of APIs for automating data validation and enrichment tasks. It helps developers streamline workflows and ensure data quality with minimal effort.
- [Addressfinder](https://composio.dev/toolkits/addressfinder) - Addressfinder is a data quality platform for verifying addresses, emails, and phone numbers. It helps you ensure accurate customer and contact data every time.
- [Agenty](https://composio.dev/toolkits/agenty) - Agenty is a web scraping and automation platform for extracting data and automating browser tasks—no coding needed. It streamlines data collection, monitoring, and repetitive online actions.
- [Ambee](https://composio.dev/toolkits/ambee) - Ambee is an environmental data platform providing real-time, hyperlocal APIs for air quality, weather, and pollen. Get precise environmental insights to power smarter decisions in your apps and workflows.
- [Ambient weather](https://composio.dev/toolkits/ambient_weather) - Ambient Weather is a platform for personal weather stations with a robust API for accessing local, real-time, and historical weather data. Get detailed environmental insights directly from your own sensors for smarter apps and automations.
- [Anonyflow](https://composio.dev/toolkits/anonyflow) - Anonyflow is a service for encryption-based data anonymization and secure data sharing. It helps organizations meet GDPR, CCPA, and HIPAA data privacy compliance requirements.
- [Api ninjas](https://composio.dev/toolkits/api_ninjas) - Api ninjas offers 120+ public APIs spanning categories like weather, finance, sports, and more. Developers use it to supercharge apps with real-time data and actionable endpoints.
- [Api sports](https://composio.dev/toolkits/api_sports) - Api sports is a comprehensive sports data platform covering 2,000+ competitions with live scores and 15+ years of stats. Instantly access up-to-date sports information for analysis, apps, or chatbots.
- [Apify](https://composio.dev/toolkits/apify) - Apify is a cloud platform for building, deploying, and managing web scraping and automation tools called Actors. It lets you automate data extraction and workflow tasks at scale—no infrastructure headaches.
- [Autom](https://composio.dev/toolkits/autom) - Autom is a lightning-fast search engine results data platform for Google, Bing, and Brave. Developers use it to access fresh, low-latency SERP data on demand.
- [Beaconchain](https://composio.dev/toolkits/beaconchain) - Beaconchain is a real-time analytics platform for Ethereum 2.0's Beacon Chain. It provides detailed insights into validators, blocks, and overall network performance.
- [Big data cloud](https://composio.dev/toolkits/big_data_cloud) - BigDataCloud provides APIs for geolocation, reverse geocoding, and address validation. Instantly access reliable location intelligence to enhance your applications and workflows.
- [Bigpicture io](https://composio.dev/toolkits/bigpicture_io) - BigPicture.io offers APIs for accessing detailed company and profile data. Instantly enrich your applications with up-to-date insights on 20M+ businesses.
- [Bitquery](https://composio.dev/toolkits/bitquery) - Bitquery is a blockchain data platform offering indexed, real-time, and historical data from 40+ blockchains via GraphQL APIs. Get unified, reliable access to complex on-chain data for analytics, trading, and research.
- [Brightdata](https://composio.dev/toolkits/brightdata) - Brightdata is a leading web data platform offering advanced scraping, SERP APIs, and anti-bot tools. It lets you collect public web data at scale, bypassing blocks and friction.
- [Builtwith](https://composio.dev/toolkits/builtwith) - BuiltWith is a web technology profiler that uncovers the technologies powering any website. Gain actionable insights into analytics, hosting, and content management stacks for smarter research and lead generation.
- [Byteforms](https://composio.dev/toolkits/byteforms) - Byteforms is an all-in-one platform for creating forms, managing submissions, and integrating data. It streamlines workflows by centralizing form data collection and automation.
- [Cabinpanda](https://composio.dev/toolkits/cabinpanda) - Cabinpanda is a data collection platform for building and managing online forms. It helps streamline how you gather, organize, and analyze responses.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and Here MCP?

With a standalone Here MCP server, the agents and LLMs can only access a fixed set of Here tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Here and many other apps based on the task at hand, all through a single MCP endpoint.

### Can I use Tool Router MCP with Pydantic AI?

Yes, you can. Pydantic AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Here tools.

### Can I manage the permissions and scopes for Here while using Tool Router?

Yes, absolutely. You can configure which Here scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

### How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Here data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)