Get started with HERE Location Reasoning

Beta availability
HERE Location Reasoning is currently available to beta participants. For information about joining the beta, visit HERE Location Reasoning.

Connect to HERE Location Reasoning through the Model Context Protocol (MCP), authenticate with HERE OAuth 2.0, start a session, discover available tools, and call a tool.

Prerequisites

Get your HERE Access Key ID and HERE Access Key Secret from your HERE onboarding materials.
Install Python 3.10 or later.
Install httpx:
```
python3 -m pip install httpx
```

Verify the installation:

python3 -c "import httpx; print(httpx.__version__)"

For authentication details, see How to authorize with OAuth 2.0.

Step 1: Generate a HERE token

Authenticate with your HERE Access Key ID and Access Key Secret before calling the HERE Location Reasoning MCP endpoint. The following example signs an OAuth 2.0 client credentials request and returns a short-lived JSON Web Token (JWT) that you include as a bearer token in MCP requests.

import base64
import hashlib
import hmac
import time
import urllib.parse
import uuid
import httpx

TOKEN_URL = "https://account.api.here.com/oauth2/token"
KEY_ID = "<YOUR_ACCESS_KEY_ID>"
KEY_SECRET = "<YOUR_ACCESS_KEY_SECRET>"


def get_here_token() -> str:
    """Generate a HERE OAuth2 token using HMAC-SHA256 signed client credentials."""
    ts = str(int(time.time()))
    nonce = uuid.uuid4().hex

    params = sorted([
        ("grant_type", "client_credentials"),
        ("oauth_consumer_key", KEY_ID),
        ("oauth_nonce", nonce),
        ("oauth_signature_method", "HMAC-SHA256"),
        ("oauth_timestamp", ts),
        ("oauth_version", "1.0"),
    ])

    encoded = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
    base = "&".join([
        "POST",
        urllib.parse.quote(TOKEN_URL, safe=""),
        urllib.parse.quote(encoded, safe=""),
    ])
    key = urllib.parse.quote(KEY_SECRET, safe="") + "&"
    sig = base64.b64encode(
        hmac.new(key.encode(), base.encode(), hashlib.sha256).digest()
    ).decode()

    auth = (
        f'OAuth realm="",'
        f'oauth_consumer_key="{KEY_ID}",'
        f'oauth_nonce="{nonce}",'
        f'oauth_signature="{urllib.parse.quote(sig, safe="")}",'
        f'oauth_signature_method="HMAC-SHA256",'
        f'oauth_timestamp="{ts}",'
        f'oauth_version="1.0"'
    )

    resp = httpx.post(
        TOKEN_URL,
        content=b"grant_type=client_credentials",
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": auth,
        },
        timeout=30,
    )
    resp.raise_for_status()
    try:
        return resp.json()["access_token"]
    except KeyError as exc:
        raise RuntimeError("The token response did not include an access token.") from exc


token = get_here_token()
print(f"Token obtained: {token[:20]}...")

The code signs a request with your Access Key Secret and exchanges it for a short-lived JWT.

Step 2: Initialize the MCP session

Send an initialize request to start an MCP session. The server returns its capabilities and an Mcp-Session-Id header. Include this header in later requests to maintain session context.

HERE_LOCATION_REASONING_URL = "https://hlr.here.ai/mcp"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

resp = httpx.post(HERE_LOCATION_REASONING_URL, json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2025-03-26",
        "capabilities": {},
        "clientInfo": {"name": "quickstart", "version": "1.0"},
    },
}, headers=headers, timeout=30)
resp.raise_for_status()

session_id = resp.headers.get("mcp-session-id")
if not session_id:
    raise RuntimeError("The initialize response did not include Mcp-Session-Id.")

headers["Mcp-Session-Id"] = session_id
print("Session established.")

A successful request prints Session established.

Step 3: Send initialized notification

Notify the server that your client completed initialization and is ready to use MCP features:

resp = httpx.post(HLR_URL, json={
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {},
}, headers=headers, timeout=30)
resp.raise_for_status()

This is a notification, so it has no id field. It signals that the handshake is complete.

📘
Note
If you skip this notification, some MCP servers may reject later requests or behave unpredictably.

Step 4: Discover available tools

List the tools exposed by the HERE Location Reasoning MCP server. The tools/list response returns each tool's name, description, and schema, so your application can discover tools without hardcoding them.

resp = httpx.post(HERE_LOCATION_REASONING_URL, json={
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {},
}, headers=headers, timeout=30)
resp.raise_for_status()

tools = resp.json()["result"]["tools"]
print(f"Available tools: {[t['name'] for t in tools]}")

This returns the full list of tools with their input and output schemas.

Step 5: Call a tool

Call a tool with the tools/call method. Include the tool name and its required arguments.

resp = httpx.post(HERE_LOCATION_REASONING_URL, json={
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "hlr___geocode",
        "arguments": {"q": "Alexanderplatz, Berlin"},
    },
}, headers=headers, timeout=30)
resp.raise_for_status()

result = resp.json()["result"]
print(result)

This calls the hlr___geocode tool and returns structured coordinate and address data. The tool arguments are:

{
  "name": "hlr___geocode",
  "arguments": {
    "q": "Alexanderplatz, Berlin"
  }
}

A successful call returns a result similar to the following:

{
  "title": "Alexanderplatz",
  "address": {
    "label": "Alexanderplatz, 10178 Berlin, Germany",
    "city": "Berlin",
    "postalCode": "10178",
    "countryName": "Germany",
    "countryCode": "DEU"
  },
  "position": {
    "lat": 52.52192,
    "lng": 13.41321
  }
}

Each response value has its own field. For example, use position.lat and position.lng to place the result on a map, or use address.city and address.countryName to filter or store the result.

Troubleshooting

Issue	Root cause	Solution
Authentication fails	The access key ID or secret is missing or incorrect.	Verify your HERE credentials and regenerate the token.
Session initialization fails	The bearer token is missing, expired, or invalid.	Generate a new token and retry the initialize request.
Later requests fail after initialization	The `Mcp-Session-Id` header is missing.	Include the session ID returned by the initialize response in subsequent requests.
The server returns an MCP error	The request is invalid or the tool is unavailable.	Review the error code and message, then verify the request against the schema returned by `tools/list`.
Tool call fails	The tool name or arguments do not match the tool schema.	Call `tools/list` and verify the tool name and required arguments.

Next steps

Connect and authenticate — Comprehensive reference for auth flows, multiple token methods (Python + CLI), session management, and error handling.
HERE Location Reasoning integration examples — Ready-to-run integrations using LangChain, Strands Agents, PydanticAI, and more.
HERE Location Reasoning tools reference — Complete list of available location tools.