> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gabin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Give an AI agent read access to French companies, officers, buildings and territories through the Gabin MCP server at mcp.gabin.ai.

The Gabin MCP server exposes the same data as the [REST API](https://docs.gabin.ai/quickstart.md) to any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io): Claude, ChatGPT, Claude Code, Cursor, VS Code or your own agent. The agent gets 18 read-only tools: search companies, read a company profile with its officers and accounts, geocode an address, open a building with its owners and energy certificates, run a multi-criteria search in a city.

| | |
| - | - |
| Server URL | `https://mcp.gabin.ai/mcp` |
| Transport | Streamable HTTP, stateless: one `POST /mcp` per JSON-RPC message, JSON responses. `GET` and `DELETE /mcp` answer `405`. |
| Authentication | OAuth 2.1 (issuer `https://gabin.ai`) or an API key as `Authorization: Bearer gab_live_…` |
| Resource metadata | `https://mcp.gabin.ai/.well-known/oauth-protected-resource` |
| Tools | 18, all read-only, [listed here](https://docs.gabin.ai/mcp/tools.md) |
| Scope | `read` (the only one) |

> [card] [Connect a client](https://docs.gabin.ai/mcp/connect.md)
>
> Step-by-step for Claude, Claude Code, ChatGPT, Cursor, VS Code and any other MCP client.

## Authentication

Every request to `/mcp` carries a Bearer token. Two kinds work, and both are tied to your Gabin account:

> [tab] OAuth 2.1 (connectors)
>
> For clients that log the user in themselves, such as the Claude and ChatGPT connectors. The server is an OAuth protected resource ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)): its metadata names `https://gabin.ai` as the authorization server. The client reads `https://gabin.ai/.well-known/oauth-authorization-server`, registers itself (dynamic client registration, public client), and sends you to the consent screen at `https://gabin.ai/oauth/autoriser`, where you sign in if needed and approve. PKCE (`S256`) is required.
>
> Access tokens (`gat_…`) last 1 hour; refresh tokens (`gar_…`) last 30 days and rotate on each use. You can revoke an application at any time from [gabin.ai/compte/api](https://gabin.ai/compte/api), under "Applications autorisées". Details in [Authentication](https://docs.gabin.ai/authentication.md).

> [tab] API key (Bearer)
>
> For clients that take a fixed header, such as Claude Code, Cursor or your own code. Create a key at [gabin.ai/compte/api](https://gabin.ai/compte/api) (a verified email address is required) and send it on every request:
>
> ```http theme={null}
> Authorization: Bearer $GABIN_API_KEY
> ```
>
> Without a valid token the server answers `401` with a `WWW-Authenticate` header pointing to the resource metadata, which is how OAuth-capable clients discover the login flow.

The server never stores your token. It checks it against `GET /v1/me` on the Gabin API (one quota unit, at most once a minute per token) and forwards it as is to `/v1` for every tool call.

## Limits and usage

MCP tool calls are API calls made on your behalf. The [rate limit, daily quota and request weights](https://docs.gabin.ai/limits.md) are those of your account, shared with your API keys: 60 requests per minute and 5,000 units per UTC day on the free plan. A tool call weighs one unit, plus one unit per extra section or include it fetches (for example `get_building` with `sections: ["owners", "transactions"]` weighs 3), and `advanced_search` weighs 5 (5 more with `count`).

Your usage page at [gabin.ai/compte/api](https://gabin.ai/compte/api) shows MCP calls per tool, next to the API calls of each key.

The API accepts at most 2 concurrent requests per account. The MCP server queues the calls of a token beyond that instead of failing them, so a tool that reads several resources at once, or a client that calls several tools in parallel, works without a `429`.

## Tools

All tools are read-only (`readOnlyHint: true`, `idempotentHint: true`) and return two things: a short text, one line per object with its identifiers and `gabin_url`, and `structuredContent` that matches the tool's published `outputSchema`. Lists are paginated by cursor and say so in the text. Errors come back as tool results with `isError: true` and a message that names the API error code and what to do next.

> [card] [Companies and officers](https://docs.gabin.ai/mcp/tools.md#companies-and-officers)
>
> `search_companies`, `get_company`, `list_company_establishments`, `get_establishment`, `search_officers`, `get_officer`, `lookup_reference`

> [card] [Buildings and real estate](https://docs.gabin.ai/mcp/tools.md#buildings-and-real-estate)
>
> `get_building`, `get_building_companies`, `list_company_buildings`, `find_buildings`, `get_parcel`

> [card] [Zones and addresses](https://docs.gabin.ai/mcp/tools.md#zones-and-addresses)
>
> `geocode_address`, `search_places`, `search_cities`, `get_zone`

> [card] [Multi-criteria search](https://docs.gabin.ai/mcp/tools.md#multi-criteria-search)
>
> `list_search_fields`, `advanced_search`

The server also sends instructions at initialization: what Gabin is, how companies, establishments, buildings, parcels and zones relate, the identifiers (SIREN, SIRET, BDNB id, INSEE, IRIS), the limits and the typical tool chains below. Field labels from the sources (activities, legal forms, roles) are in French.

## Example prompts

Each prompt chains several tools. The agent picks them from the descriptions; you do not have to name them.

> [accordion] From an address to the companies and owners of a building
>
> > Who is located at 40 rue de Bruxelles, Villeurbanne, and who owns the building?
>
> 1. `geocode_address` with `q: "40 rue de Bruxelles Villeurbanne"` returns the normalized address and the BDNB building matched at house-number level.
> 2. `get_building` with that id and `sections: ["owners", "energy"]` returns the characteristics, the corporate owners from land files and the energy certificates.
> 3. `get_building_companies` lists the occupants (establishments matched to the building) and the owners, with each company summary.
>
> For a named place instead of an address (a hospital, a residence, a shop), the agent uses `search_places`.

> [accordion] From a company to its establishments and buildings
>
> > Where does Atelier Thermique operate, and what premises does it own?
>
> 1. `search_companies` with `q: "atelier thermique"` returns matching legal units with their SIREN.
> 2. `get_company` with `include: ["officers", "financials"]` returns the profile, the RNE officers and up to 10 fiscal years of accounts.
> 3. `list_company_establishments` lists every SIRET with its address, position and matched building.
> 4. `list_company_buildings` merges occupied and owned buildings, with the SIRETs located in each.

> [accordion] Zone prospecting with the multi-criteria search
>
> > In Villeurbanne, find residential buildings built before 1975 with an energy class F or G and at least 10 dwellings.
>
> 1. `search_cities` with `q: "villeurb"` returns the INSEE code `69266`.
> 2. `list_search_fields` with `target: "buildings"` returns the catalog: field ids, operators, units and accepted values.
> 3. `advanced_search` with `target: "buildings"`, `zone: { type: "city", code: "69266" }`, the conditions on construction year, energy class and dwellings, and `count: true` for the total and breakdowns.
> 4. For one result, `get_building` with `sections: ["condominium", "owners"]` names the professional manager and the corporate owners.
>
> For companies of a given activity in an area, the agent uses `lookup_reference` (`kind: "naf"`) to find the NAF codes, then `search_companies` with `naf` and `insee`.

> [accordion] A person and their mandates
>
> > Which companies does Claire Montessuy run?
>
> 1. `search_officers` with `q: "Claire Montessuy"` returns matching identities, each with one company to tell namesakes apart.
> 2. `get_officer` with the id returns every mandate of that identity and a bounded graph of the other officers of those companies.

> [accordion] Figures of a territory
>
> > What are the sale prices, rents and median income in Villeurbanne?
>
> `get_zone` with `level: "city"`, `code: "69266"` and `include_market: true` returns the districts of the city and the market sheet: prices per m² by segment (DVF), rents, population and income, yearly, for the city and every level containing it.

> [!NOTE]
>
> Every record carries a `gabin_url`, its page on gabin.ai. Ask the agent to cite it as the source.

## Data rules

The server applies the same [data rules](https://docs.gabin.ai/data.md) as the API. A company under SIRENE partial diffusion shows no person name, an address limited to the city, no building and no officers. Owners from the land files, condominium managers and permit applicants are legal entities; officers are named with their month and year of birth, and sole proprietorships under their registered name. No contact details (email, phone) are published.

## For bulk work

The MCP server is made for an agent reasoning over a few objects at a time. For extraction, enrichment or anything that pages through thousands of results, use the [REST API](https://docs.gabin.ai/quickstart.md) at `https://api.gabin.ai/v1` with the same credentials: same data, same limits, no model in the loop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.