# Clientes

> Documentación para agentes: índice en https://api.staging.flowence.tech/connect/docs/llms.txt. La documentación completa requiere una credencial de Flowence Connect: la herramienta `docs` del servidor MCP o la clave API en el encabezado Authorization.

Todos los clientes usan el mismo servidor MCP remoto:

```text
https://api.staging.flowence.tech/mcp
```

El transporte es Streamable HTTP (POST con respuestas JSON). Hay dos formas de autenticarse:

- **OAuth (recomendado para asistentes).** Agregue la URL como conector en su asistente, con su sesión iniciada, y
  autorice en Flowence. No hace falta copiar claves; pegar la URL en una conversación no conecta la cuenta.
- **Clave API.** Viaja en el encabezado `Authorization: Bearer <clave>`. Guárdela en la variable de entorno
  `FLOWENCE_API_KEY` (o cárguela desde su almacén de secretos). Los ejemplos de esta página la leen de esa variable sin
  escribirla: no pegue la clave en comandos, en archivos que se comparten ni en un repositorio, porque queda en el
  historial del shell, en los argumentos de los procesos o en la configuración sincronizada.

## Claude (web y escritorio)

1. En Claude, abra **Configuración → Conectores → Agregar conector personalizado**.
2. Pegue `https://api.staging.flowence.tech/mcp` y confirme.
3. Claude abre Flowence: inicie sesión, revise el consentimiento y autorice.

## ChatGPT

Requiere una cuenta de ChatGPT con la sesión iniciada: sin sesión no se pueden agregar conectores.

1. Abra `https://chatgpt.com/plugins`, elija **+** y después **Add custom MCP server**. Si no ve la opción, su plan o su
   espacio de trabajo puede exigir que active el modo desarrollador o que el administrador habilite los servidores MCP
   personalizados.
2. Escriba un nombre (por ejemplo, Flowence), pegue `https://api.staging.flowence.tech/mcp` como URL de conexión y elija autenticación OAuth.
3. Acepte el aviso de riesgo, cree el plugin e instálelo.
4. Cuando ChatGPT lo pida, inicie sesión en Flowence, revise el consentimiento y autorice.
5. En una conversación nueva, escriba `@`, elija Flowence y haga su consulta.

Los nombres de los menús de ChatGPT pueden cambiar; la URL y la autorización en Flowence son siempre las mismas.

## Claude Code con OAuth

```bash
claude mcp add --transport http flowence https://api.staging.flowence.tech/mcp
```

Luego ejecute `/mcp` en Claude Code y elija autenticar: se abre el navegador para autorizar en Flowence.

## Claude Code con clave API

```bash
claude mcp add --scope project --transport http flowence https://api.staging.flowence.tech/mcp \
  --header 'Authorization: Bearer ${FLOWENCE_API_KEY}'
```

Las comillas simples son importantes: el shell no reemplaza la variable, así que en `.mcp.json` queda la referencia
`${FLOWENCE_API_KEY}` y Claude Code la reemplaza por la clave cada vez que se conecta. Con comillas dobles la clave
quedaría escrita en la configuración. El archivo equivalente es:

```json
{
  "mcpServers": {
    "flowence": {
      "type": "http",
      "url": "https://api.staging.flowence.tech/mcp",
      "headers": { "Authorization": "Bearer ${FLOWENCE_API_KEY}" }
    }
  }
}
```

Luego, en una sesión de Claude Code, pida por ejemplo: "Use Flowence y dígame cuánto hay vencido por moneda".

## Cursor

Con OAuth, agregue solo la URL (`"url": "https://api.staging.flowence.tech/mcp"`) y autorice cuando Cursor lo pida. Con clave API, agregue el
servidor en `~/.cursor/mcp.json` (o en `.cursor/mcp.json` del proyecto):

```json
{
  "mcpServers": {
    "flowence": {
      "url": "https://api.staging.flowence.tech/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FLOWENCE_API_KEY}"
      }
    }
  }
}
```

## Codex

```bash
codex mcp add flowence --url https://api.staging.flowence.tech/mcp --bearer-token-env-var FLOWENCE_API_KEY
```

Codex lee la clave de la variable `FLOWENCE_API_KEY` en cada conexión; la configuración solo guarda el nombre de la
variable.

## Visual Studio Code

Agregue el servidor en `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "flowence-api-key",
      "description": "Clave API de Flowence Connect",
      "password": true
    }
  ],
  "servers": {
    "flowence": {
      "type": "http",
      "url": "https://api.staging.flowence.tech/mcp",
      "headers": {
        "Authorization": "Bearer ${input:flowence-api-key}"
      }
    }
  }
}
```

## Otros clientes MCP

Cualquier cliente que admita servidores MCP remotos por HTTP con encabezados personalizados funciona con esta
configuración:

| Campo | Valor |
| --- | --- |
| Tipo o transporte | `http` o `streamable-http` |
| URL | `https://api.staging.flowence.tech/mcp` |
| Encabezado | `Authorization: Bearer <clave>` |

El servidor también acepta la clave en el encabezado `X-API-Key`. Nunca la envíe en la URL.

### Scripts con Python urllib

Si utiliza `urllib.request`, defina un `User-Agent` que identifique su integración, por ejemplo
`User-Agent: mi-integracion-flowence/1.0`. Con el agente predeterminado (`Python-urllib/3.x`), la protección del
perímetro puede responder `403` antes de que el pedido llegue a la API. El script de las skills de Flowence ya envía
su propio `User-Agent`.

## API REST

La API REST expone las mismas operaciones que el servidor MCP. En estos ejemplos, `-H @-` hace que curl lea el
encabezado de la entrada estándar: la clave no aparece en los argumentos del proceso ni en el historial del shell.

```bash
curl -s -H @- "https://api.staging.flowence.tech/connect/v1/status" <<< "Authorization: Bearer $FLOWENCE_API_KEY"

curl -s -H @- "https://api.staging.flowence.tech/connect/v1/debtors?query=norte&limit=10" <<< "Authorization: Bearer $FLOWENCE_API_KEY"
```

La especificación OpenAPI está en `https://api.staging.flowence.tech/connect/v1/openapi.json`. Vea [API REST](https://api.staging.flowence.tech/connect/docs/api-rest).

## Verificar la conexión

Llame a la herramienta `status` (o a `GET https://api.staging.flowence.tech/connect/v1/status`). La respuesta indica:

- el tenant y el usuario responsable;
- los alcances de la credencial y su vencimiento;
- los límites de pedidos;
- los próximos pasos sugeridos.

Si recibe `401`, la clave es inválida, venció, fue revocada o ya no puede usarse (por ejemplo, porque cambió el rol
del usuario responsable). La respuesta no indica el motivo: quien administra Flowence Connect lo ve en **Flowence
Connect → Actividad**. Vea [Límites y errores](https://api.staging.flowence.tech/connect/docs/limites-y-errores).