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:

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)

En Claude, abra Configuración → Conectores → Agregar conector personalizado.
Pegue https://api.staging.flowence.tech/mcp y confirme.
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.

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.
Escriba un nombre (por ejemplo, Flowence), pegue https://api.staging.flowence.tech/mcp como URL de conexión y elija autenticación OAuth.
Acepte el aviso de riesgo, cree el plugin e instálelo.
Cuando ChatGPT lo pida, inicie sesión en Flowence, revise el consentimiento y autorice.
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

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

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:

{
  "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):

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

Codex

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:

{
  "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.

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.

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.