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

# Connect a client

> Add the Gabin MCP server to Claude, Claude Code, ChatGPT, Cursor, VS Code or any MCP client, with OAuth or an API key.

The server lives at `https://mcp.gabin.ai/mcp`. Clients that log you in themselves (Claude, ChatGPT) use OAuth: you approve them once on gabin.ai. Clients that take a fixed header (Claude Code, Cursor, VS Code, your own code) can use OAuth when they support it, or an API key sent as `Authorization: Bearer`.

> [!NOTE]
>
> Both paths need a Gabin account with a verified email address. Create one at [gabin.ai/compte/inscription](https://gabin.ai/compte/inscription); the consent screen and the key page both refuse an unverified address.

## Before you start

> [tab] OAuth (no key to copy)
>
> Nothing to prepare. When the client connects for the first time, it registers itself with `https://gabin.ai` and opens the Gabin consent screen in your browser. Sign in if you are not, check the application name and the return domain, and approve. The client receives an access token valid 1 hour and a refresh token valid 30 days; it renews them on its own.

> [tab] API key
>
> 1. Open [gabin.ai/compte/api](https://gabin.ai/compte/api) and create a key. It is shown once; copy it.
> 2. Keep it out of files you share. In the examples below it is read from the `GABIN_API_KEY` environment variable:
>
> ```bash theme={null}
> export GABIN_API_KEY="gab_live_…"
> ```
>
> A key has the same rights and the same [limits](https://docs.gabin.ai/limits.md) as an OAuth token. Up to 5 keys can be active at once; delete one from the same page to revoke it.

## Claude (claude.ai and Claude Desktop)

Custom connectors are configured through your Claude account and work in Claude on the web and in Claude Desktop. The connection comes from Anthropic's servers, not from your machine. Steps as described in [Anthropic's guide to custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

**1. Add a custom connector**

Go to **Customize > Connectors**, click **Add**, then **Add custom connector**. Give it a name (for example `Gabin`) and enter the server URL:

```text theme={null}
https://mcp.gabin.ai/mcp
```

Click **Continue**. Claude reads the server's metadata and detects that it uses OAuth.

**2. Choose how to sign in**

Under **Authentication**, choose **Sign in now**. Under **OAuth client**, choose **Register automatically**: Gabin supports dynamic client registration. Leave **Request headers** empty unless you prefer an API key over OAuth, in which case add a header `Authorization` with the value `Bearer gab_live_…` and choose **No sign in**.

Click **Add**.

**3. Approve on gabin.ai**

A Gabin page opens. Sign in if needed, then approve the application. Claude shows the connector as connected.

**4. Use it in a conversation**

In a chat, open the **+** menu, then **Connectors**, and enable Gabin. Ask a question such as "Who occupies the building at 40 rue de Bruxelles in Villeurbanne?". Claude calls the tools and cites the `gabin_url` of each record if you ask for sources.

On Team and Enterprise plans, an Owner adds the connector once from **Organization settings > Connectors**; each member then connects to it from **Customize > Connectors**. Free accounts are limited to one custom connector.

> [!TIP]
>
> To disconnect Claude from your account, revoke it from [gabin.ai/compte/api](https://gabin.ai/compte/api), under **Applications autorisées**. Claude will ask you to sign in again the next time it uses the connector.

## Claude Code

Claude Code supports both OAuth and a fixed header. Reference: [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

> [tab] OAuth
>
> Add the server, then authenticate from the `/mcp` command:
>
> ```bash theme={null}
> claude mcp add --transport http gabin https://mcp.gabin.ai/mcp
> ```
>
> In a Claude Code session, run `/mcp`, select `gabin` and follow the steps in the browser: Gabin asks you to sign in and approve. Claude Code keeps the tokens and renews them.

> [tab] API key
>
> Pass the key as a header. Claude Code sends it on every request and never asks you to sign in:
>
> ```bash theme={null}
> claude mcp add --transport http gabin https://mcp.gabin.ai/mcp \
>   --header "Authorization: Bearer $GABIN_API_KEY"
> ```
>
> The shell expands `$GABIN_API_KEY` once, when you run the command, and the key is stored in the configuration. To keep it out of the configuration, write the server in `.mcp.json` with a variable that Claude Code expands at startup:
>
> ```json .mcp.json theme={null}
> {
>   "mcpServers": {
>     "gabin": {
>       "type": "http",
>       "url": "https://mcp.gabin.ai/mcp",
>       "headers": {
>         "Authorization": "Bearer ${GABIN_API_KEY}"
>       }
>     }
>   }
> }
> ```

By default the server is added to the current project only (`--scope local`). Use `--scope user` to have it in every project, or `--scope project` to share a `.mcp.json` with your team (keep the key in an environment variable in that case). Check the connection with `claude mcp list`.

## ChatGPT

ChatGPT connects to remote MCP servers with OAuth; Gabin supports the dynamic client registration that ChatGPT uses. Steps as described in [OpenAI's developer documentation](https://developers.openai.com/api/docs/mcp), which does not state which plans can add a custom server: "account and workspace policies apply", so a workspace administrator may have to allow it.

**1. Add a custom MCP server**

Open ChatGPT's custom server page (`chatgpt.com/plugins` at the time of writing), click the **+** button, then **Add custom MCP server**. Give it a name and a description.

**2. Enter the URL and sign in**

Under **Connection**, enter the server URL with its `/mcp` path:

```text theme={null}
https://mcp.gabin.ai/mcp
```

Select OAuth as the authentication, read the warning and confirm. ChatGPT sends you to gabin.ai to sign in and approve, then lists the 18 tools it discovered. Create the connection.

**3. Use it in a chat**

Start a new conversation, type `@` in the prompt box and select Gabin, then ask your question. ChatGPT asks before calling tools unless you allow them for the conversation.

> [!WARNING]
>
> ChatGPT's deep research and company knowledge expect a server to implement two tools named `search` and `fetch`. Gabin does not expose them yet: the server works in regular chat, where ChatGPT calls the tools [listed here](https://docs.gabin.ai/mcp/tools.md), not as a deep research source.

## Cursor

Cursor reads MCP servers from `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` for every project. Both OAuth and headers are supported on Streamable HTTP servers. Reference: [Cursor MCP documentation](https://cursor.com/docs/context/mcp).

```json API key (~/.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "gabin": {
      "url": "https://mcp.gabin.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GABIN_API_KEY}"
      }
    }
  }
}
```

```json OAuth (~/.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "gabin": {
      "url": "https://mcp.gabin.ai/mcp"
    }
  }
}
```

`${env:GABIN_API_KEY}` is resolved from your shell profile or system environment; remote servers do not support `envFile`. Without a header, Cursor detects that the server requires sign-in and runs the OAuth flow (authorization code with PKCE, registering as a public client): approve on gabin.ai when the browser opens. Servers are enabled, disabled and signed in from **Customize** in the sidebar; connection logs are in the Output panel under **MCP Logs**.

> [!NOTE]
>
> The OAuth flow works from the desktop app (local return address `http://localhost:…/callback`) and from Cursor on the web and Cloud Agents (`https://www.cursor.com/agents/mcp/oauth/callback`).

## VS Code

VS Code adds MCP servers through the Command Palette or a JSON file. Reference: [Add MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

**1. Add the server**

Run **MCP: Add Server** from the Command Palette, choose **HTTP (HTTP or Server-Sent Events)**, enter `https://mcp.gabin.ai/mcp` and a server ID such as `gabin`, then the destination (user or workspace).

Or write the file yourself. In `.vscode/mcp.json`, with the key prompted once and stored in VS Code's secret storage:

```json .vscode/mcp.json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "gabin-api-key",
      "description": "Gabin API key (gab_live_…)",
      "password": true
    }
  ],
  "servers": {
    "gabin": {
      "type": "http",
      "url": "https://mcp.gabin.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:gabin-api-key}"
      }
    }
  }
}
```

Without the `headers` block, the server requires sign-in: review the authentication prompt VS Code shows on the first connection and approve on gabin.ai. Gabin accepts the `vscode://` and `https://vscode.dev/redirect` return addresses.

**2. Start and check**

Run **MCP: List Servers** to start the server and show its output. The 18 Gabin tools appear in the chat's tools picker.

**3. Ask**

In chat, name the server in your request when it helps: "Use the Gabin MCP server to list the companies at 40 rue de Bruxelles, Villeurbanne."

Workspace files inherit Workspace Trust and are not a secret store: keep the key in an input or an environment variable, never in the file.

## Any other MCP client

Give the client the URL and, unless it handles OAuth, the header:

| Setting | Value |
| - | - |
| URL | `https://mcp.gabin.ai/mcp` |
| Transport | Streamable HTTP (`POST` only, JSON responses) |
| Header | `Authorization: Bearer $GABIN_API_KEY` |
| OAuth discovery | `https://mcp.gabin.ai/.well-known/oauth-protected-resource` |

OAuth clients find the authorization server from the resource metadata (`authorization_servers: ["https://gabin.ai"]`), then its endpoints at `https://gabin.ai/.well-known/oauth-authorization-server`. Dynamic client registration (`POST https://gabin.ai/oauth/register`, public clients only), PKCE `S256`, the `resource` parameter ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)) with `https://mcp.gabin.ai` or `https://mcp.gabin.ai/mcp`, and `iss` in the authorization response are supported. Client ID Metadata Documents are not. Return addresses are limited to known connectors, `http://localhost` (any port), `cursor:`, `vscode:` and `vscode-insiders:` schemes.

To check a token from the shell, initialize a session and list the tools. The `Accept` header must list both `application/json` and `text/event-stream`, or the transport answers `406`; `MCP-Protocol-Version` is optional:

```bash Initialize theme={null}
curl -s -X POST https://mcp.gabin.ai/mcp \
  -H "Authorization: Bearer $GABIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}'
```

```bash List tools theme={null}
curl -s -X POST https://mcp.gabin.ai/mcp \
  -H "Authorization: Bearer $GABIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

```bash Call a tool theme={null}
curl -s -X POST https://mcp.gabin.ai/mcp \
  -H "Authorization: Bearer $GABIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_cities","arguments":{"q":"villeurb"}}}'
```

The server is stateless: no `initialize` is needed before a `tools/call`, no session id is issued, and each request is independent.

## Managing access

> [card] [Create or delete a key](https://gabin.ai/compte/api)
>
> [gabin.ai/compte/api](https://gabin.ai/compte/api). A verified email is required. Deleting a key invalidates it within a minute.

> [card] [Revoke an application](https://gabin.ai/compte/api)
>
> Same page, under **Applications autorisées**: each OAuth client with its name, return domain and date. Revoking it invalidates its access and refresh tokens; the application has to ask for your consent again.

Deleting your account revokes every key and every application.

## Troubleshooting

> [accordion] 401 with a WWW-Authenticate header
>
> The request had no token, or a token Gabin no longer accepts (expired, revoked, deleted key). The header tells OAuth clients where to start:
>
> ```http theme={null}
> HTTP/1.1 401 Unauthorized
> WWW-Authenticate: Bearer resource_metadata="https://mcp.gabin.ai/.well-known/oauth-protected-resource", scope="read"
> ```
>
> With `error="invalid_token"` at the end, a token was sent and refused. With an API key, check that the header reads `Authorization: Bearer gab_live_…` (the key is case-sensitive, with no quotes) and that the key is still listed on [gabin.ai/compte/api](https://gabin.ai/compte/api). With OAuth, reconnect the client: its refresh token may have expired after 30 days without use, or the application was revoked.
>
> Inside a tool result, the same situation reads `UNAUTHENTICATED: Gabin no longer accepts this credential…` with `isError: true`.

> [accordion] 429 rate\_limited on the HTTP request
>
> ```json theme={null}
> { "error": "rate_limited", "error_description": "Too many failed authentications from this address." }
> ```
>
> Too many invalid tokens were sent from your IP address; a valid token always passes. Fix the token and wait for the `Retry-After` delay.

> [accordion] RATE\_LIMITED in a tool result
>
> Your account went over 60 weighted requests per minute. The message gives the delay: `RATE_LIMITED: Rate limit reached (60 weighted requests per minute). Retry in 12 s.` The agent is told to wait; a loop that fans out many calls at once should spread them. The limit is shared with your API keys. See [Limits](https://docs.gabin.ai/limits.md).

> [accordion] QUOTA\_EXCEEDED in a tool result
>
> The daily quota of your account (5,000 units per UTC day) is spent, across API keys and MCP clients: `QUOTA_EXCEEDED: Daily quota of this account reached (5000 units per UTC day). It resets at 00:00 UTC.` `advanced_search` weighs 5 units, each extra section of `get_building` or include of `get_company` one more: ask for the sections you need. Your usage by tool is on [gabin.ai/compte/api](https://gabin.ai/compte/api).

> [accordion] 405 Method Not Allowed
>
> The client opened a `GET /mcp` stream or sent `DELETE /mcp`. The server is stateless and answers `405` with `Allow: POST`; clients that follow the Streamable HTTP transport fall back to POST on their own. Nothing to do.

> [accordion] 503 unavailable
>
> The Gabin API did not answer the token check. Retry after a few seconds (`Retry-After: 5`).

> [accordion] The consent screen says the email address must be verified
>
> Open the verification link Gabin sent you (or request one from [gabin.ai/compte](https://gabin.ai/compte)), then start the connection again from the client.

> [accordion] ChatGPT deep research does not see the server
>
> Expected: deep research and company knowledge look for `search` and `fetch` tools, which Gabin does not expose. Use the server in a regular chat.


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