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

https://api.geosci.de/mcp

Transport

Streamable HTTP

Authentication

Your API key, sent as the header Authorization: Bearer <your API key>

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

list_ratings

Lists the ratings your API key can use, with their descriptions. Assistants usually call this first.

rate_location

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 (relative).

explain_rating

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 rating_pois.

rating_pois

Lists the points of interest a rating considered (shops, stops, schools, …) with distances and travel times.

rate_area

Summarises ratings over an area given as a polygon: mean, median, minimum, maximum per rating, for all ratings or the ones named.

find_best_areas

Finds the best-scoring parts of a polygon, for one rating or for a weighted combination of ratings.

find_similar_areas

Finds areas whose ratings resemble those of a reference area or location, within a search radius.

find_similar_locations

Finds locations around a given one whose ratings, over the ratings named, resemble the given location’s.

compare_locations

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_rating answers 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_rating is computed at the exact point, while rate_location reads 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_rating with the status NO_DATA, the others with a message. explain_rating and rating_pois can 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 that rate_location tells 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!