# Facelocal MCP

Connect your AI assistant to the Facelocal documentation. The MCP
(Model Context Protocol) server lets you consult guides, search APIs and read
integration examples in Portuguese or English.

## Connection

**Server URL**

```text
https://facelocal.dev/api/mcp
```

- Transport: **Streamable HTTP**.
- Public, read-only access. No key or login required.
- Documents follow the SDK version available on the website.

## Cursor

Add this configuration to your project's `.cursor/mcp.json` file.
If the file already exists, add `facelocal` to the `mcpServers` object without
replacing other servers.

```json
{
  "mcpServers": {
    "facelocal": {
      "url": "https://facelocal.dev/api/mcp"
    }
  }
}
```

Enable the server in Cursor's MCP settings and confirm the connection.

## VS Code

Add this configuration to your project's `.vscode/mcp.json` file.
If the file already exists, add `facelocal` to the `servers` object.

```json
{
  "servers": {
    "facelocal": {
      "type": "http",
      "url": "https://facelocal.dev/api/mcp"
    }
  }
}
```

Run **MCP: List Servers**, select `facelocal` and start the server.
Confirm trust in the server when prompted by the editor.

## Available tools

| Tool | Usage |
| --- | --- |
| `get_sdk_info` | Get the SDK version and available guides. |
| `search_documentation` | Search documentation excerpts and sections. |
| `read_documentation` | Read a guide or section, with pagination. |

All tools accept `locale`: `pt-BR` or `en`. The default is `pt-BR`.

Guides use the identifiers `visao-geral`, `integracao`, `resultado-json`,
`mcp` and `licencas` in both languages.

Search results include links and section identifiers. Pass the identifier as
`section` to read just that part. To continue a paginated read, pass the
`nextLine` value as `startLine`.

## Usage example

In your editor's chat:

> Use the facelocal MCP to look up liveness and Face Match integration for my React Native app.

Example search arguments:

```json
{
  "query": "runFaceLocalVerification",
  "locale": "en",
  "limit": 5
}
```

Example read arguments:

```json
{
  "slug": "integracao",
  "locale": "en",
  "startLine": 1,
  "maxLines": 120
}
```

Guides are also available as MCP resources, for example:

```text
facelocal://docs/pt-BR/integracao
facelocal://docs/en/integracao
```

## Scope and privacy

The MCP only queries public documentation. It does not run liveness or
Face Match, receive images, access the gallery or process biometric data.
Those operations remain in the SDK integrated into the application.

The MCP does not unlock paid source code, validate coupons, make payments
or access files in the visitor's project.

## Troubleshooting

- Use a client compatible with **Streamable HTTP**. This server does not offer
  the legacy SSE transport.
- The URL is not a web page. Opening the address in a browser returns HTTP 405;
  configure it in your MCP client, which sends POST requests.
- HTTP 429 indicates too many requests. Wait for the time specified in the
  `Retry-After` header before retrying.
- If the editor does not list the tools, restart the connection and check the URL.

To integrate the SDK, see the [integration guide](INTEGRATION.md) and the
[JSON result contract](JSON-RESULT.md).