Connection & Authentication Guide

This guide provides comprehensive reference for authenticating with HERE Location Reasoning and working with the MCP protocol. For a quick end-to-end walkthrough, see Getting Started first.

Prerequisites

To connect to HERE Location Reasoning you need:

HERE Access Key ID — provided during customer onboarding
HERE Access Key Secret — provided during customer onboarding

These credentials are used to generate a short-lived OAuth2 bearer token.

Endpoint

All MCP requests are sent as HTTP POST to the HERE Location Reasoning endpoint:

https://hlr.ai.here.com/mcp

Requests must use:

Method: POST
Content-Type: application/json
Body: JSON-RPC 2.0 payload

Authentication

HERE OAuth2 Token Generation

The endpoint uses HERE Account OAuth2 tokens for authentication. You generate a token by signing a request with your Access Key Secret using HMAC-SHA256 and exchanging it for a JWT.

Token endpoint: https://account.api.here.com/oauth2/token

The resulting JWT is short-lived. When it expires, generate a new one using the same flow.

Python Example

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()
    return resp.json()["access_token"]

OLP CLI Example

If you have the HERE OLP CLI installed:

# Create credentials file at ~/.here/credentials.properties
cat > ~/.here/credentials.properties << EOF
here.token.endpoint.url=https://account.api.here.com/oauth2/token
here.client.id=<YOUR_CLIENT_ID>
here.access.key.id=<YOUR_ACCESS_KEY_ID>
here.access.key.secret=<YOUR_ACCESS_KEY_SECRET>
EOF

# Import credentials
olp credentials import gateway ~/.here/credentials.properties

# Get token
olp api token get --profile gateway

Token Format

Include the token in requests as:

Authorization: Bearer <HERE_JWT>

MCP Protocol

Communication uses a JSON-RPC 2.0 MCP interface. Requests are stateful — you establish a session and maintain it across requests.

Session Lifecycle

The standard request flow is:

initialize — Establish a session. Returns server capabilities and Mcp-Session-Id header.
notifications/initialized — Notify the server your client is ready (no response body).
tools/list — Discover available tools and their schemas.
tools/call — Execute a tool (authentication required).

Session Affinity

After initialize, the response includes a Mcp-Session-Id header. Include this header in all subsequent requests:

Mcp-Session-Id: <value-from-initialize-response>

This ensures your requests route to the same session. Without it, requests may fail or reach a different session.

Authentication Requirements by Method

Method	Requires Bearer Token	Description
`initialize`	No	Establish MCP session, receive server info
`notifications/initialized`	No	Confirm client readiness after init
`tools/list`	No	Discover available tools and schemas
`resources/list`	No	List available MCP resources
`resources/read`	No	Read an MCP resource by URI
`tools/call`	Yes	Execute a location tool

Supported Methods

The following JSON-RPC methods are supported:

initialize — Start a new MCP session
notifications/initialized — Client readiness notification
tools/list — List available tools
tools/call — Invoke a tool
resources/list — List available resources (e.g., usage policies)
resources/read — Read a specific resource

Example: Full Session (cURL)

HLR_URL="https://hlr.ai.here.com/mcp"
TOKEN="<YOUR_HERE_JWT>"

# 1. Initialize
curl -s -D - -X POST "$HLR_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl", "version": "1.0"}
    }
  }'
# Note the Mcp-Session-Id header in the response

SESSION_ID="<from-response-header>"

# 2. Initialized notification
curl -s -X POST "$HLR_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

# 3. List tools
curl -s -X POST "$HLR_URL" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# 4. Call a tool (auth required)
curl -s -X POST "$HLR_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "geocode",
      "arguments": {"q": "Berlin, Germany"}
    }
  }'

Error Handling

HTTP 401 — Unauthorized

Returned when:

The Authorization header is missing on a tools/call request
The Bearer token is expired
The token signature is invalid

Recovery: Generate a fresh token using the OAuth2 flow and retry the request.

HTTP 403 — Forbidden

Returned when the token is valid but the authorization check fails (your account does not have access to HERE Location Reasoning).

Recovery: Contact your HERE account representative to verify your entitlements.

HTTP 429 — Too Many Requests

Returned when your request rate exceeds the per-customer limit.

Recovery: Back off and retry after a short delay. If you consistently hit this limit, contact your HERE account representative to discuss rate limit adjustments.

JSON-RPC Errors

Tool execution errors are returned as standard JSON-RPC error responses within a 200 HTTP response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32000,
    "message": "validation failed: ..."
  }
}

These indicate issues with tool parameters (invalid input, missing required fields) rather than authentication problems.

What's Next

Examples — Ready-to-run framework integrations using LangChain, Strands Agents, PydanticAI, and more.
Tools Reference — Complete list of available location tools.