3. MCP Server (Model Context Protocol)¶
Note
Last verified 2026-11-18 against server version 0.2.3. The places_near section describes version
0.2.5, which sends WHG a circle query instead of a bounding box.
WHG runs a small, read-only Model Context Protocol (MCP) server. It lets an AI assistant, or any other MCP client, search WHG’s public place data and fetch full place records, with the attribution and licence terms of each source attached to what comes back.
It is meant for people who use an AI assistant and want it to look places up in WHG directly rather than guess. It is not a replacement for the Entity API or the Reconciliation API: it is a thin, deliberately limited layer over them, sized for occasional interactive lookups. For bulk work, use those APIs with your own token.
3.1. Status¶
Experimental. Tool names, parameters and limits may change.
Read-only. No tool can create, change or delete anything in WHG.
Anonymous. No WHG account, API token or key is needed to use it, and the server never asks for one.
Live since 2026-11-18.
Public data only. It reads WHG through an ordinary, non-staff service account with no datasets or groups of its own, so it sees what any member of the public would see.
3.2. Endpoint¶
https://mcp.whgazetteer.org/
The server speaks MCP’s streamable HTTP transport at the root path (/). It is stateless and
answers with plain JSON (Content-Type: application/json), not an event stream, so no session needs
to be opened or kept alive.
3.3. Connecting a client¶
Any MCP client that supports remote servers over streamable HTTP can connect. No authentication step is needed.
3.3.1. Claude Code¶
claude mcp add --transport http whg https://mcp.whgazetteer.org/
whg is the local name for the server and can be anything. Add --scope user to make it available in
all your projects, or --scope project to record it in the project’s .mcp.json.
3.3.2. Claude Desktop and claude.ai¶
Remote servers are added as a custom connector rather than in a configuration file: Settings →
Connectors → Add → Add custom connector, then enter https://mcp.whgazetteer.org/ as the URL.
3.3.3. Other clients¶
Configuration formats differ between clients. Many use a JSON block of this shape; the one below is
the form Claude Code uses in .mcp.json. Check your client’s documentation for the exact field names
(some use streamable-http as the type, or a different key for the URL).
{
"mcpServers": {
"whg": {
"type": "http",
"url": "https://mcp.whgazetteer.org/"
}
}
}
3.3.4. Checking the connection by hand¶
The server can be called directly with curl. Both Accept values are required by the transport.
curl -s https://mcp.whgazetteer.org/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Calling a tool:
curl -s https://mcp.whgazetteer.org/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"status","arguments":{}}}'
Up to version 0.2.3, the serverInfo.version in the initialize answer was the version of the MCP
software library the server is built on. Since 0.2.4 it is the server’s own version, as the status
tool also reports.
3.4. Tools¶
There are seven tools. Each returns a JSON object, sent as the text of a single MCP text content
item. Parameters outside the stated ranges are rejected before anything is sent to WHG, except
limit, which is clamped to 1–50.
3.4.1. search_places¶
Search places by name, with optional filters. This runs one query against WHG’s Reconciliation API.
Parameter |
Type |
Default |
Notes |
|---|---|---|---|
|
string, at most 200 characters |
none |
Name to match. Fuzzy, ranked matching (the Reconciliation API’s default mode). |
|
string, at most 200 characters |
none |
Matches names containing this text (the API’s |
|
string |
none |
ISO 3166-1 alpha-2 country codes, comma-separated, e.g. |
|
string |
none |
Feature class letters, comma-separated, e.g. |
|
string |
none |
AAT place type ids, comma-separated, e.g. |
|
integer, -10000 to 2100 |
none |
Keeps places whose dates do not rule out that year. Places with no dates at all are dropped. |
|
integer |
none |
Restrict to one WHG dataset id. |
|
integer |
20 |
1–50. |
One of name or name_contains is required. year is sent as a one-year window (start and end
both set to that year) with the API’s default possibly temporal mode.
Example, {"name": "Lund", "ccode": "SE", "limit": 2}, shortened:
{
"results": [
{
"id": "place:osm:n7472552741",
"name": "Lund",
"score": 100,
"match": true,
"namespace": "osm",
"alt_names": ["lund"],
"ccodes": ["SE"],
"repr_point": [14.598302, 59.168672], // [lon, lat]
"has_geom": false,
"place_types": [{"identifier": "isolated_dwelling", "label": "osm"}],
"confidence": 100.0
// …
}
// …
],
"namespaces_searched": ["osm", "whg"],
"attribution": { "sources": { "osm": { … }, "whg": { … } }, … }
}
The fields of each candidate are those of a Reconciliation API result: see
Result Format and Interpreting confidence.
3.4.2. get_place¶
Fetch full records, in Linked Places Format, from the Entity API.
Parameter |
Type |
Default |
Notes |
|---|---|---|---|
|
array of strings or integers, 1–10 items |
required |
A WHG number ( |
Ids are de-duplicated and fetched one at a time, in the order given. The answer is
{"places": [...]}, plus {"errors": [{"id": ..., "error": ...}]} for any id that could not be
fetched; one failing id does not stop the others. A malformed id fails the whole call before anything
is fetched.
Each record keeps its own attribution object. A geometry larger than 20 kB is replaced by its type,
its bounding box ([west, south, east, north]) and a note saying the full geometry was omitted. The
full geometry can be fetched from the Entity API.
Example, {"place_ids": ["place:gn:6515785"]}, shortened:
{
"places": [
{
"@id": "https://whgazetteer.org/entity/place:gn:6515785/api",
"type": "Feature",
"properties": {"title": "Grand Hotel - Lund", "ccodes": ["SE"], "source_id": "gn:6515785"},
"names": [{"toponym": "Grand Hotel - Lund"}],
"types": [{"identifier": "HTL", "label": "S", "sourceLabel": "S.HTL", "aat_ids": []}],
"geometry": {"type": "Point", "coordinates": [13.18915, 55.70384]},
"links": [], "descriptions": [], "depictions": [], "relations": [], "when": {},
"attribution": {"id": "gn", "name": "GeoNames", "citation_text": "GeoNames geographical database, Unxos GmbH.", … }
}
]
}
3.4.3. places_near¶
Places whose representative point lies within a radius of a point, nearest first.
Parameter |
Type |
Default |
Notes |
|---|---|---|---|
|
number, -180 to 180 |
required |
Longitude of the centre. |
|
number, -90 to 90 |
required |
Latitude of the centre. |
|
number, greater than 0, at most 100 |
25 |
Radius in kilometres. |
|
integer |
20 |
1–50. |
How it works (version 0.2.5 and later):
The server sends WHG a circle-only query: the centre, the radius,
relation: within(the place must lie inside the circle) and a request for as many places as WHG will give. WHG returns at most 500 places, in no particular order. It matches the circle as a disc of H3 cells that can reach up to about 1.3 times the radius, so some of them lie just outside it.The server computes the great-circle distance from the centre to each place’s representative point (
repr_point), keeps those withinkm, and sorts them nearest first. Places without a representative point are dropped.It returns the first
limitof them, each with an addeddistance_km(rounded to the metre).
Because WHG’s 500 are not chosen by distance, when WHG returns all 500, the places nearest the
centre may not be among them. The answer then carries "may_be_incomplete": true and a note
saying so, with a suggested smaller km; a smaller radius finds the nearest places. Below 500 the
answer holds every place WHG found in the circle.
Up to version 0.2.4 the server asked for the bounding box around the circle instead, and WHG returned at most 50 places for it, because WHG’s circle-only query returned nothing until a fix of 2026-11-18.
Example, {"lon": 13.19, "lat": 55.70, "km": 3, "limit": 3}, shortened. The answer has this shape; the
places listed were returned by version 0.2.3 and may differ now:
{
"results": [
{"id": "place:osm:r4055481", "name": "Södra innerstaden", "namespace": "osm",
"repr_point": [13.184345, 55.698347], "distance_km": 0.399, … },
{"id": "place:osm:n13018928457", "name": "Silversmeden 1927 - 1974", "distance_km": 0.404, … },
{"id": "place:gn:6515785", "name": "Grand Hotel - Lund", "distance_km": 0.43, … }
],
"namespaces_searched": ["gn", "osm", "whg"],
"attribution": { … }
// plus "may_be_incomplete": true and a "note" when WHG returned its maximum of 500
}
In spatial results score is 0 and match is false: they are not name matches.
3.4.4. places_in_bbox¶
Places whose geometry lies inside a bounding box.
Parameter |
Type |
Default |
Notes |
|---|---|---|---|
|
number, -180 to 180 |
required |
|
|
number, -90 to 90 |
required |
|
|
number, -180 to 180 |
required |
Must not be less than |
|
number, -90 to 90 |
required |
Must not be less than |
|
integer |
20 |
1–50. |
The box may be at most 10 degrees wide and 10 degrees high. The answer has the same shape as
search_places.
3.4.5. list_sources¶
No parameters. Returns WHG’s list of source gazetteers (namespaces) as
GET /api/sources/ gives it.
3.4.6. get_attribution¶
Attribution and licence terms for what you are citing, from GET /api/attribution/.
Parameter |
Type |
Default |
Notes |
|---|---|---|---|
|
string |
none |
Source namespaces, comma-separated, e.g. |
|
array of integers, at most 50 |
none |
WHG numeric place ids. |
With neither parameter, only WHG’s own overlay attribution is returned.
3.4.7. status¶
No parameters. Returns the server’s name and version, the WHG instance it reads from, and
"read_only": true. It makes no call to WHG.
3.5. Attribution and licences¶
WHG’s sources do not share one licence (see Source Terms and Attribution). The server passes the terms through unchanged:
search_places,places_nearandplaces_in_bboxcarry WHG’sattributionblock for the sources in the answer, and each result names its source innamespace.Each record from
get_placecarries its ownattributionobject.get_attributiongives the terms for any namespaces or place ids on request.
If you reuse or quote place data obtained this way, cite its sources as their terms require. The server tells AI assistants this when they connect, but it cannot make them do it: check what your assistant gives you before you publish it.
Some sources do not allow WHG to redistribute their records. A get_place request for such a place
comes back as an error for that id: “This place’s source does not allow WHG to redistribute it.”
This is WHG’s 451 answer and no credential
changes it. Search results show this in advance: the source’s entry in the attribution block has
"redistributable": false.
3.6. Limits¶
Limit |
Value |
|---|---|
Results per search ( |
1–50, default 20 |
Places |
500 (WHG’s maximum for one query) |
Ids per |
10 |
Ids per |
50 |
Bounding box |
at most 10 × 10 degrees |
Radius |
at most 100 km |
Name text |
at most 200 characters |
Any single answer from WHG |
1.5 MB |
Geometry in a |
20 kB, then replaced by type and bounding box |
Long text fields (names, descriptions, …) |
cut at 2,000 characters, marked |
Time allowed for each call to WHG |
30 seconds |
Request rate, per client IP address (IPv6: per /64) |
30 per minute, with a burst of 20; at most 10 connections at once |
Request size |
64 KB |
Daily budget, shared by all callers |
2,000 calls to WHG per day, reset at 00:00 UTC |
The daily budget counts calls from the server to WHG, not calls to the server: a get_place request
for 10 ids uses 10, and status uses none.
3.7. Errors¶
Errors are returned as an MCP tool result with "isError": true and a plain-language message. Rate
limiting and host checks happen before the server, as HTTP status codes.
You see |
Meaning |
What to do |
|---|---|---|
HTTP |
Your address exceeded the request rate or connection limit. |
Slow down and retry. |
“This service’s daily request allowance is used up; try again after 00:00 UTC.” |
The shared daily budget is spent. |
Try again after midnight UTC, or use WHG’s APIs with your own token. |
“WHG’s API quota for this service is exhausted; try again later.” |
WHG’s API refused the server’s own account for quota. |
Try again later. |
“WHG rejected this service’s token. …” |
The server’s own credentials failed upstream. Nothing you send can cause or fix this. |
Report it (see below). |
“This place’s source does not allow WHG to redistribute it.” |
WHG’s |
Obtain the record from the source under its own terms. |
“Not found.” |
No such place id. |
Check the id. |
“Not a WHG place id: …” |
The id has the wrong form. |
Use a number or an id as search results give it. |
“Bounding box too large: …”, “east/north must not be less than west/south.” |
|
Use a smaller box. |
“WHG refused the query: …” |
WHG answered that one query with an error instead of results, for example a radius over WHG’s own 500 km limit. Not the same as “nothing found”. |
Change the query as the message says. |
“Give at least |
|
Add one. |
“WHG’s answer is too large; …” |
WHG’s answer exceeded 1.5 MB. |
Ask for fewer results or fewer places. |
“WHG did not answer in time; …”, “Could not reach WHG.” |
WHG was slow or unreachable. |
Retry later. |
|
WHG’s gazetteer index did not answer that query. An empty result here does not mean the place does not exist. |
Retry. |
HTTP |
The request’s |
Browser-based clients running on another website cannot call the server directly. |
3.8. Differences from the legacy API endpoints¶
The server uses only POST /reconcile, GET /entity/place:<id>/api, GET /api/sources/ and
GET /api/attribution/. It does not use the legacy /api/db/, /api/index/, /api/place/,
/api/spatial/ or /api/geojson/ endpoints. If you know those endpoints, note that:
Name search is fuzzy and ranked.
/api/db/matched names as case-insensitive substrings and did not rank them. Here,nameis ranked fuzzy matching, andname_containsgives substring matching.yearkeeps places whose dates do not rule out the year, and drops places that have no dates.There is no
collectionfilter, and the spatial tools have no feature-class or dataset filter.get_placetakes at most 10 ids (the legacy endpoints allowed more), and returns Linked Places Format from the Entity API.Results are capped at 50 per call, against 200 for
/api/db/.Ids can be namespaced. Results include places from source gazetteers (
place:gn:…,place:osm:…), not only places in WHG datasets.
3.9. Privacy and data handling¶
The server stores no user data. It has no accounts, no sessions and no database. Each request is answered and forgotten.
What is logged. The web server in front of it records, for each request: the client IP address, the time, the request line, the status code, the response size, the
User-Agent, timings and whether a rate limit applied. It does not record request bodies, so tool arguments are not in that log. Logs are rotated in the usual way. The server’s own process log records the kind of each MCP request and its status, not its arguments.What reaches WHG. The server calls WHG’s public services with its own dedicated, non-staff service account, never with a caller’s credentials. It does not pass on your IP address. WHG’s own web server logs these calls like any other API request; they identify the service, not you.
Treat what you type into a search as you would any query sent to a public web service: do not put personal information in it.
3.10. Security¶
Read-only. The server can make only four kinds of request to WHG, each checked against an exact list (method and path):
GET /api/sources/,GET /api/attribution/,GET /entity/place:<id>/apiandPOST /reconcile, which is a search and writes nothing. Anything else is refused before it is sent. It follows no redirects.Its credentials stay with it. The service token is read from the server’s environment, sent only to WHG, and never put in a log, an error message or a tool result. It is never accepted from a caller.
Untrusted text. Place names, descriptions and links in results are contributed by third parties. An AI assistant should treat them as data, never as instructions, and the server tells connecting assistants so. If an assistant’s behaviour changes after reading a result, treat that as a problem to report.
3.11. Reporting problems¶
Report problems and feedback as a GitHub Issue, as for any other part of WHG (see Issues & Discussions). Please include the tool, the arguments and the message you received, and the time (UTC).
3.12. For developers¶
The source, deployment notes and tests are in the mcp/ directory of the
feature/mcp-server branch
of the WHG website repository.