Key Takeaways
- AI for geology often starts with old geologic maps, the maps that show which rocks lie where. Many of them now exist only as scanned pictures.
- Before an AI assistant can study such a picture, someone has to load it into the map program, a bit like checking a book into a library. The program then gives the map a catalogue number.
- The program only accepts ordinary picture files, not PDFs, and only from folders it has permission to open. Loading the same map twice is harmless: it simply gets the same number again.
TL;DR
An AI assistant cannot study a scanned geologic map until the map has been loaded into its map program. Loading checks that the file is a picture the program can read, sits in a folder it may open, and is not too big. The map then gets a catalogue number that the AI uses from then on, without ever seeing where the file is stored on your computer.
What Is geomap_register_map?
Stratigraphic Amenity is Eigenform’s open-source (MIT) MCP server for scanned geologic maps. Before the server can detect a legend, georeference a sheet or look up faults and earthquakes for an area, an agent has to register the map.
geomap_register_map does that. Its only input is a path, for example {"path": "./data/map.png"}. The server records the map in a small registry on disk and hands back identifiers that the map tools understand.
Run the capability check first. Registration needs no optional installs, but the tools you plan to call after it may not be ready.
How Do I Load a Scanned Geologic Map With AI?
Registration fails for three common reasons: the file is in the wrong place, in the wrong format, or too big. Each one returns a specific error code the agent can act on.
Put the file inside an allowed root
The server only reads files inside its allowed roots. An operator sets them with GEOMAP_MCP_ALLOWED_ROOTS; by default they are the server’s data and cache folders. A file anywhere else returns disallowed_path with the message “Path is outside configured MCP allowed roots.”
The server resolves the path where it runs, not where the agent runs. A relative path starts from the server’s working directory. The server also follows symbolic links to the real file before the check, so a link cannot smuggle in a file from outside. If the file does not exist at all, the error is artifact_not_found.
Use a supported format under 200 MiB
Supported formats are PNG, JPEG, TIFF, WebP and GIF. The server judges the format from the file extension, so a map saved as a PDF returns unsupported_media. Export the page as a TIFF or PNG at full resolution first.
The size limit for a source map is 200 MiB. A larger file returns oversize_image, with the observed and allowed byte counts in the error details. Either use a smaller export or ask the operator to raise the limit.
Keep the map ID and geomap:// URIs
A successful call returns map_id, map_uri (geomap://maps/<id>), source_uri (geomap://maps/<id>/source) and the detected mime_type. It also returns source_path_redacted: true: the local path stays on the server, and the agent only ever handles the opaque geomap:// handle.
Registration is idempotent. The same file, once the server resolves its path, always maps to the same map ID, so retrying a call or registering a map twice does not create duplicates. Passing an existing geomap://maps/<id> URI as the path simply returns that map’s record.
Where Registration Fits in an AI for Geology Workflow
The map ID is the key for the rest of an AI for geology workflow. Detecting the map layout and legend uses it next, then georeferencing ties pixels to real coordinates, and knowledge queries look up geology for the mapped area.
Two limits are easy to miss. The server caps resource reads at 50 MiB. A source map between 50 and 200 MiB still registers and works with the tools, but the server lists its source_uri as UNREADABLE, so an agent cannot read the image back. In addition, deleting or moving the server’s cache folder invalidates every stored URI, and there is no cleanup tool.
Allowed roots stop accidental access; they are not a sandbox. The server still runs with its process’s file permissions.
Older scanned maps usually come from the same archives as old drillhole data, often recorded in mixed coordinate systems. That clean-up problem also slows brownfield exploration with AI.
FAQs
Why does geomap_register_map say my path is outside the allowed roots?
The file resolves to a folder the server is not allowed to read. By default only the server’s data and cache folders are allowed. Move the map into one of them, or ask the operator to add its folder to GEOMAP_MCP_ALLOWED_ROOTS. Remember that relative paths start from the server’s working directory, not the agent’s.
Can I register a PDF of a scanned map?
No. The server accepts PNG, JPEG, TIFF, WebP and GIF images and decides the format from the file extension. Export the PDF page as a full-resolution TIFF or PNG, place it inside an allowed folder, and register that image instead.
What happens if I register the same map twice?
The server creates nothing new. Registration is idempotent: the same file, once the server resolves its path, always returns the same map ID and URIs. An agent can therefore retry a failed or interrupted call safely, and two agents registering the same scan on one server share a single map record.
What is a geomap:// URI?
It is an opaque handle the server issues instead of a local file path. geomap://maps/<id> identifies the registered map and geomap://maps/<id>/source the original image. Later tools accept the map ID or URI, and an MCP client can read the resources directly, within the 50 MiB read limit.
Try It With Geocluster
Stratigraphic Amenity is one of the Geocluster tools, MCP servers that let AI agents work with geology data and maps.
Once a map is registered, the next big step is georeferencing a scanned geological map from ground control points.
