Connect an AI assistant (MCP)
You can give an AI assistant direct access to the GeoSci ratings, so that it can answer questions such as "How well is this flat connected to public transport, and why?" by itself. The connection uses the Model Context Protocol (MCP), an open standard that Claude, Cursor, VS Code and many agent frameworks support.
All you need is the server address and an API key with MCP access enabled. MCP access is enabled per API key; contact us at hello@geosci.de to enable it for yours.
Server URL |
|
Transport |
Streamable HTTP |
Authentication |
Your API key, sent as the header |
Without MCP access, the server answers 403 Forbidden and the assistant cannot connect.
Beyond that, the assistant acts with your API key: it sees exactly the ratings your key gives you,
and its requests count towards your usage like any other API request (see Usage and billing).
Set up your client
In the examples below, replace $GEOSCI_API_KEY with your API key, or set it as an environment variable.
Claude Code
claude mcp add --transport http geosci https://api.geosci.de/mcp \
--header "Authorization: Bearer $GEOSCI_API_KEY"
Start a new Claude Code session afterwards; claude mcp list shows whether the server is connected.
Claude Desktop
Claude Desktop connects to servers that authenticate with a header through the
mcp-remote bridge, which needs Node.js.
Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"geosci": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.geosci.de/mcp",
"--header",
"Authorization:${GEOSCI_AUTH}"
],
"env": {
"GEOSCI_AUTH": "Bearer <your API key>"
}
}
}
}
Restart Claude Desktop to load it.
| The Connectors that you add in claude.ai or in the Claude apps sign in with OAuth, which the GeoSci server does not offer yet. Use Claude Code, the Claude Desktop configuration above, or another client from this page. |
Cursor
Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects:
{
"mcpServers": {
"geosci": {
"url": "https://api.geosci.de/mcp",
"headers": {
"Authorization": "Bearer <your API key>"
}
}
}
}
VS Code
Add the server to .vscode/mcp.json. VS Code asks for the key once and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "geosci-api-key",
"description": "GeoSci API key",
"password": true
}
],
"servers": {
"geosci": {
"type": "http",
"url": "https://api.geosci.de/mcp",
"headers": {
"Authorization": "Bearer ${input:geosci-api-key}"
}
}
}
}
Other clients and agent frameworks
Any MCP client that speaks Streamable HTTP and can send a header works. Point it at https://api.geosci.de/mcp and send
Authorization: Bearer <your API key> with every request. The server keeps no session between requests.
To try the server without an assistant, run the MCP Inspector
with npx @modelcontextprotocol/inspector, choose Streamable HTTP, and add the Authorization header.
What the assistant can do
| Tool | What it does |
|---|---|
|
Lists the ratings your API key can use, with their descriptions. Assistants usually call this first. |
|
Rates a location, for all ratings or the ones named, with their sub-ratings if asked.
Optionally also returns how the location ranks against residential areas nearby ( |
|
Explains one rating at a location in plain language: what drives the score and which sub-ratings it combines.
The points of interest behind a rating come from |
|
Lists the points of interest a rating considered (shops, stops, schools, …) with distances and travel times. |
|
Summarises ratings over an area given as a polygon: mean, median, minimum, maximum per rating, for all ratings or the ones named. |
|
Finds the best-scoring parts of a polygon, for one rating or for a weighted combination of ratings. |
|
Finds areas whose ratings resemble those of a reference area or location, within a search radius. |
|
Finds locations around a given one whose ratings, over the ratings named, resemble the given location’s. |
|
Scores how closely each of a list of locations resembles a given one, over the ratings named. |
The last five tools need the analytics:read permission on your API key. The tools that find areas return each area
as a point inside it and its bounding box rather than its outline, which an assistant cannot use; the
/areas/best, /areas/composite and /areas/similar routes of the REST API return the outlines.
No tool changes or deletes data. rate_location, explain_rating, rating_pois, find_similar_locations and
compare_locations save the coordinate as one of your places the first time it is used, as the
/places/{coordinate} routes of the REST API do, so they are not marked read-only. Scores lie between 0 and 1, and 1
is always the desirable end, as everywhere in the API.
Things to know
-
Coordinates, not addresses. The tools take a longitude and latitude. Most assistants find the coordinates of an address on their own; if yours cannot, give it the coordinates.
-
English explanations.
explain_ratinganswers in English; the assistant can translate for you. -
Places are created for you. As with the REST API, every location the assistant rates is stored as one of your places (see Places).
-
Explanations are computed live. The score in
explain_ratingis computed at the exact point, whilerate_locationreads our precomputed ratings, so the two can differ slightly. -
Outside our data. Where we have no data, such as at sea or abroad, the tools say so:
explain_ratingwith the statusNO_DATA, the others with a message.explain_ratingandrating_poiscan also answer there with a score of 0 or no points of interest. The assistant is told that such an answer says nothing about the location, and thatrate_locationtells whether there is data. -
Ratings in plain words. The assistant is asked to describe a rating by what it counts, taken from its description, rather than by its title alone. For an overview or a comparison it reports the scores, each explained by what it counts; for a question about specific facilities it names places nearby. These places illustrate what a rating counts; they are not necessarily the ones its score was computed from.
Usage and billing
Each tool call that reads data is billed as the API request it makes, for example rate_location as
GET /places/{longitude},{latitude}/ratings. Connecting, and listing the available tools, is free.
An assistant may call several tools to answer one question; you can follow your usage at
https://api.geosci.de/customers/me/billing/api-usage.
More questions?
Contact us at hello@geosci.de!