# Geo
Read-only access to rag_dev.geo_entities (~2.5M GeoNames rows). Resolve names, inspect countries/cities/admin/marine/places, coastal filters, haversine distance, nearby radius search, airport IATA lookup, and embedding-neighbor search.
**Service id:** `geo`
**Version:** `0.2.0`
**Status:** `available`
## Authentication
MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)
**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).
Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.
```http
Authorization: Bearer mcp_...
```
Cursor `mcp.json` example:
```json
{
"mcpServers": {
"geo": {
"url": "https://mcp.glc-rag.hu/mcp",
"headers": {
"Authorization": "Bearer mcp_YOUR_TOKEN"
}
}
}
}
```
## Tools
### `geo_status`
Geo DB health, read-only mode, and row counts by entity_type.
**Input schema:**
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
**Examples:**
```json
{}
```
### `geo_resolve`
Resolve a name, ISO2/ISO3, or IATA code to geo entities (best matches).
**Input schema:**
```json
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"entity_type": {
"type": "string",
"enum": [
"country",
"city",
"place",
"admin1",
"admin2",
"marine"
]
},
"country_code": {
"type": "string",
"description": "ISO2 filter"
},
"place_kind": {
"type": "string",
"enum": [
"hill",
"mountain",
"peak",
"volcano",
"lake",
"lakes",
"reservoir",
"waterfall",
"island",
"islands",
"atoll",
"airport",
"heliport",
"park",
"nature_reserve",
"wildlife_reserve",
"pass",
"ruin",
"castle",
"museum",
"monument",
"oilfield"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
}
},
"required": [
"query"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"query": "Budapest",
"entity_type": "city"
}
```
```json
{
"query": "HU"
}
```
```json
{
"query": "BUD"
}
```
### `geo_get`
Full entity profile by geoname_id (columns + complete payload).
**Input schema:**
```json
{
"type": "object",
"properties": {
"geoname_id": {
"type": "integer"
}
},
"required": [
"geoname_id"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"geoname_id": 3054643
}
```
### `geo_text_search`
Fuzzy text search (pg_trgm) over names and search_text.
**Input schema:**
```json
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"entity_type": {
"type": "string",
"enum": [
"country",
"city",
"place",
"admin1",
"admin2",
"marine"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": [
"query"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"query": "Balaton",
"entity_type": "place"
}
```
### `geo_semantic_search`
Embedding-space neighbors around the best name match (uses stored e5 vectors; no write to DB). Falls back to text search if anchor has no embedding.
**Input schema:**
```json
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"entity_type": {
"type": "string",
"enum": [
"country",
"city",
"place",
"admin1",
"admin2",
"marine"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": [
"query"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"query": "Budapest",
"entity_type": "city",
"limit": 10
}
```
### `geo_country_get`
Country facts by ISO2 or geoname_id (currency, languages, coastal flags, …).
**Input schema:**
```json
{
"type": "object",
"properties": {
"iso2": {
"type": "string"
},
"geoname_id": {
"type": "integer"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"iso2": "HU"
}
```
### `geo_country_list`
List countries, optionally filtered by continent_code.
**Input schema:**
```json
{
"type": "object",
"properties": {
"continent_code": {
"type": "string",
"description": "e.g. EU, AS, AF"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 252,
"default": 50
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"continent_code": "EU",
"limit": 20
}
```
### `geo_country_neighbours`
Neighbouring countries via payload.neighbours ISO2 list.
**Input schema:**
```json
{
"type": "object",
"properties": {
"iso2": {
"type": "string"
}
},
"required": [
"iso2"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"iso2": "HU"
}
```
### `geo_country_capital`
Resolve country capital via capital_geoname_id.
**Input schema:**
```json
{
"type": "object",
"properties": {
"iso2": {
"type": "string"
}
},
"required": [
"iso2"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"iso2": "IT"
}
```
### `geo_admin1_list`
List admin1 regions for a country (e.g. Italian regions).
**Input schema:**
```json
{
"type": "object",
"properties": {
"country_code": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
"required": [
"country_code"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"country_code": "IT"
}
```
### `geo_admin1_get`
Get admin1 by admin_code (e.g. IT.03) or geoname_id.
**Input schema:**
```json
{
"type": "object",
"properties": {
"admin_code": {
"type": "string"
},
"geoname_id": {
"type": "integer"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"admin_code": "IT.03"
}
```
### `geo_admin2_list`
List admin2 for a country, optionally under an admin1 short code.
**Input schema:**
```json
{
"type": "object",
"properties": {
"country_code": {
"type": "string"
},
"admin1_code": {
"type": "string",
"description": "Short code e.g. 03"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
"required": [
"country_code"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"country_code": "IT",
"admin1_code": "03"
}
```
### `geo_admin2_get`
Get admin2 by admin_code or geoname_id.
**Input schema:**
```json
{
"type": "object",
"properties": {
"admin_code": {
"type": "string"
},
"geoname_id": {
"type": "integer"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{}
```
### `geo_cities_search`
Search cities with filters: country, admin1 short code, population, coastal_category, distance_to_coast_km, is_capital, name query.
**Input schema:**
```json
{
"type": "object",
"properties": {
"country_code": {
"type": "string"
},
"admin1_code": {
"type": "string"
},
"min_population": {
"type": "integer"
},
"max_population": {
"type": "integer"
},
"coastal_category": {
"type": "string",
"enum": [
"direct_coastal",
"coastal",
"near_coast",
"inland"
]
},
"max_distance_to_coast_km": {
"type": "number"
},
"is_capital": {
"type": "boolean"
},
"query": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"country_code": "IT",
"admin1_code": "03",
"max_population": 500,
"max_distance_to_coast_km": 5
}
```
### `geo_coastal_cities`
Shortcut for coastal city lists (distance and/or coastal_category).
**Input schema:**
```json
{
"type": "object",
"properties": {
"country_code": {
"type": "string"
},
"admin1_code": {
"type": "string"
},
"max_distance_to_coast_km": {
"type": "number",
"default": 5
},
"coastal_category": {
"type": "string",
"enum": [
"direct_coastal",
"coastal",
"near_coast",
"inland"
]
},
"max_population": {
"type": "integer"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": [
"country_code"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"country_code": "IT",
"admin1_code": "03",
"max_distance_to_coast_km": 5
}
```
### `geo_region_cities`
Cities in an admin1 region (country_code + admin1 short code).
**Input schema:**
```json
{
"type": "object",
"properties": {
"country_code": {
"type": "string"
},
"admin1_code": {
"type": "string"
},
"min_population": {
"type": "integer"
},
"max_population": {
"type": "integer"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": [
"country_code",
"admin1_code"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"country_code": "IT",
"admin1_code": "03",
"min_population": 10000
}
```
### `geo_nearest_marine`
Precomputed nearest sea/bay for a city (nearest_marine_* + coastal fields).
**Input schema:**
```json
{
"type": "object",
"properties": {
"geoname_id": {
"type": "integer"
},
"city_query": {
"type": "string"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"city_query": "Rimini"
}
```
### `geo_marine_get`
Marine entity (sea, bay, …) by geoname_id or name query.
**Input schema:**
```json
{
"type": "object",
"properties": {
"geoname_id": {
"type": "integer"
},
"query": {
"type": "string"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"query": "Adriatic"
}
```
### `geo_distance`
Haversine distance (km) between two places (id or name). Countries use capital coords.
**Input schema:**
```json
{
"type": "object",
"properties": {
"from_id": {
"type": "integer"
},
"from_query": {
"type": "string"
},
"to_id": {
"type": "integer"
},
"to_query": {
"type": "string"
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"from_query": "Budapest",
"to_query": "Vienna"
}
```
### `geo_nearby`
Entities within radius_km of a center (id, name, or lat/lon). Optional type/kind filters.
**Input schema:**
```json
{
"type": "object",
"properties": {
"center_id": {
"type": "integer"
},
"center_query": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"radius_km": {
"type": "number",
"default": 30
},
"entity_type": {
"type": "string",
"enum": [
"country",
"city",
"place",
"admin1",
"admin2",
"marine"
]
},
"place_kind": {
"type": "string",
"enum": [
"hill",
"mountain",
"peak",
"volcano",
"lake",
"lakes",
"reservoir",
"waterfall",
"island",
"islands",
"atoll",
"airport",
"heliport",
"park",
"nature_reserve",
"wildlife_reserve",
"pass",
"ruin",
"castle",
"museum",
"monument",
"oilfield"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"center_query": "Budapest",
"radius_km": 40,
"entity_type": "place",
"place_kind": "airport"
}
```
### `geo_places_search`
Search POIs by place_kind (hill, mountain, peak, volcano, lake, lakes, reservoir, waterfall, …), country, name, elevation.
**Input schema:**
```json
{
"type": "object",
"properties": {
"place_kind": {
"type": "string",
"enum": [
"hill",
"mountain",
"peak",
"volcano",
"lake",
"lakes",
"reservoir",
"waterfall",
"island",
"islands",
"atoll",
"airport",
"heliport",
"park",
"nature_reserve",
"wildlife_reserve",
"pass",
"ruin",
"castle",
"museum",
"monument",
"oilfield"
]
},
"country_code": {
"type": "string"
},
"query": {
"type": "string"
},
"min_elevation": {
"type": "number"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"place_kind": "lake",
"country_code": "HU",
"limit": 10
}
```
### `geo_airport_lookup`
Find airports by IATA/ICAO, name, country, or near a city.
**Input schema:**
```json
{
"type": "object",
"properties": {
"iata": {
"type": "string"
},
"icao": {
"type": "string"
},
"query": {
"type": "string"
},
"country_code": {
"type": "string"
},
"near_query": {
"type": "string"
},
"radius_km": {
"type": "number",
"default": 50
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
}
},
"additionalProperties": false
}
```
**Examples:**
```json
{
"iata": "BUD"
}
```
```json
{
"near_query": "Budapest",
"radius_km": 60
}
```
### `geo_rank_places`
Rank places of a kind (e.g. highest peaks) optionally within a country.
**Input schema:**
```json
{
"type": "object",
"properties": {
"place_kind": {
"type": "string",
"enum": [
"hill",
"mountain",
"peak",
"volcano",
"lake",
"lakes",
"reservoir",
"waterfall",
"island",
"islands",
"atoll",
"airport",
"heliport",
"park",
"nature_reserve",
"wildlife_reserve",
"pass",
"ruin",
"castle",
"museum",
"monument",
"oilfield"
]
},
"country_code": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10
}
},
"required": [
"place_kind"
],
"additionalProperties": false
}
```
**Examples:**
```json
{
"place_kind": "peak",
"country_code": "IT",
"limit": 5
}
```
### `geo_place_kinds`
List supported place_kind values and entity_type values.
**Input schema:**
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
**Examples:**
```json
{}
```
## Usage notes
Prefer geo_resolve / geo_get for IDs, then specialized tools. Admin1 short codes (e.g. '03') + country_code bind to admin_code 'IT.03'. Coastal fields are precomputed on city rows. RAG database is never written.
## Errors / limits
Missing coords on countries → distance uses capital. Unknown names return empty results. Invalid API key → platform 401.
## Agent discovery
- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/geo.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://geo`