← Docs · Payloads · Markdown · Agent register · Home

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

Canonical payloads: https://mcp.glc-rag.hu/guide/geo/payload · markdown · docs://geo/payload

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.

Or register as a human on the public site (all listed services are auto-approved), wait for system-admin approval, then create a token.

Authorization: Bearer mcp_...

Cursor mcp.json example:

{
  "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:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Examples:

{}

geo_resolve

Resolve a name, ISO2/ISO3, or IATA code to geo entities (best matches).

Input schema:

{
  "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:

{
  "query": "Budapest",
  "entity_type": "city"
}

{
  "query": "HU"
}

{
  "query": "BUD"
}

geo_get

Full entity profile by geoname_id (columns + complete payload).

Input schema:

{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    }
  },
  "required": [
    "geoname_id"
  ],
  "additionalProperties": false
}

Examples:

{
  "geoname_id": 3054643
}

geo_text_search

Fuzzy text search (pg_trgm) over names and search_text.

Input schema:

{
  "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:

{
  "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:

{
  "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:

{
  "query": "Budapest",
  "entity_type": "city",
  "limit": 10
}

geo_country_get

Country facts by ISO2 or geoname_id (currency, languages, coastal flags, …).

Input schema:

{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

Examples:

{
  "iso2": "HU"
}

geo_country_list

List countries, optionally filtered by continent_code.

Input schema:

{
  "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:

{
  "continent_code": "EU",
  "limit": 20
}

geo_country_neighbours

Neighbouring countries via payload.neighbours ISO2 list.

Input schema:

{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}

Examples:

{
  "iso2": "HU"
}

geo_country_capital

Resolve country capital via capital_geoname_id.

Input schema:

{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}

Examples:

{
  "iso2": "IT"
}

geo_admin1_list

List admin1 regions for a country (e.g. Italian regions).

Input schema:

{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}

Examples:

{
  "country_code": "IT"
}

geo_admin1_get

Get admin1 by admin_code (e.g. IT.03) or geoname_id.

Input schema:

{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

Examples:

{
  "admin_code": "IT.03"
}

geo_admin2_list

List admin2 for a country, optionally under an admin1 short code.

Input schema:

{
  "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:

{
  "country_code": "IT",
  "admin1_code": "03"
}

geo_admin2_get

Get admin2 by admin_code or geoname_id.

Input schema:

{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

Examples:

{}

geo_cities_search

Search cities with filters: country, admin1 short code, population, coastal_category, distance_to_coast_km, is_capital, name query.

Input schema:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "city_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Examples:

{
  "city_query": "Rimini"
}

geo_marine_get

Marine entity (sea, bay, …) by geoname_id or name query.

Input schema:

{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Examples:

{
  "query": "Adriatic"
}

geo_distance

Haversine distance (km) between two places (id or name). Countries use capital coords.

Input schema:

{
  "type": "object",
  "properties": {
    "from_id": {
      "type": "integer"
    },
    "from_query": {
      "type": "string"
    },
    "to_id": {
      "type": "integer"
    },
    "to_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Examples:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "place_kind": "lake",
  "country_code": "HU",
  "limit": 10
}

geo_airport_lookup

Find airports by IATA/ICAO, name, country, or near a city.

Input schema:

{
  "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:

{
  "iata": "BUD"
}

{
  "near_query": "Budapest",
  "radius_km": 60
}

geo_rank_places

Rank places of a kind (e.g. highest peaks) optionally within a country.

Input schema:

{
  "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:

{
  "place_kind": "peak",
  "country_code": "IT",
  "limit": 5
}

geo_place_kinds

List supported place_kind values and entity_type values.

Input schema:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Examples:

{}

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