Conecta herramientas de IA a Flowtly con MCP de solo lectura

Cómo mantenerte al día

1. Ejecuta el comando de sincronización después de cada actualización de MCP.
2. Reinicia tu stack de agentes para aplicar los cambios de capacidades.
3. Guarda esta página para consultar las últimas indicaciones de MCP.

Qué incluye

• Reglas de autenticación, CORS y transporte para el endpoint MCP.
• Espacios de nombres de recursos de solo lectura con operaciones de listado y lectura.
• OAuth 2.0 con Dynamic Client Registration para conectar en un solo paso.
• 16 herramientas de solo lectura en 10 espacios de nombres de recursos.
• Cargas útiles JSON-RPC, ejemplos de código y consejos de integración.

Inicio rápido

• Paso 1 — Conectar (OAuth): Añade https://mcp.flowtly.eu como conector en tu herramienta de IA y autoriza el acceso de solo lectura. En Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Tutorial completo: Conectar herramientas de IA.
• Paso 2 — Inicializar: POST a https://mcp.flowtly.eu/mcp con {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — el servidor responde con las capacidades {"tools":{}}.
• Paso 3 — Listar herramientas: POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}} para descubrir las herramientas de solo lectura disponibles (p. ej. invoices.list, transactions.list, counterparties.list).
• Paso 4 — Llamar a una herramienta: POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. El resultado llega como result.content[].text (una cadena JSON).
• Todas las solicitudes usan Authorization: Bearer <YOUR_TOKEN> y Content-Type: application/json.

Transporte y autenticación

• Endpoints: POST /mcp (entrada JSON-RPC), GET /health (liveness), POST /api/chat (proxy de consola; requiere Authorization: Bearer )
• Headers: Authorization Bearer token (preferido; si no, FLOWTLY_API_KEY), el header instance es opcional y se reenvía
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Credenciales permitidas solo desde https://workspace.flowtly.eu. Nunca combine Access-Control-Allow-Origin: * con Access-Control-Allow-Credentials: true.
• API ascendente: https://api.flowtly.eu — el servidor MCP proxy todas las solicitudes a la API REST de Flowtly.

initialize

• Negocia capacidades y namespaces.
• Ejemplo de params: { "protocolVersion": "2024-11-05" }
• Capacidades de la respuesta: {"tools":{}}
• Descubrir herramientas: llama a tools/list para obtener las herramientas de solo lectura disponibles y su entrada con JSON-Schema.

tools/list

• Método: tools/list — devuelve todas las herramientas de solo lectura disponibles para tu conexión.
• Herramientas (16): invoices.list/get, transactions.list, bankAccounts.list/get, counterparties.list/get, suppliers.list, contracts.list/get/paymentScheduleLines, attachments.list/get, costGroups.list, taxGroups.list, projects.list.
• Cada entrada tiene un name, una description y un inputSchema con JSON-Schema que describe sus argumentos.
• Ejemplo: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Método: tools/call — invoca una herramienta por nombre con sus argumentos.
• Params: {"name":"<tool>","arguments":{...}}, p. ej. {"name":"invoices.list","arguments":{}}.
• Argumentos: sigue el inputSchema de la herramienta obtenido de tools/list (filtros, paginación, ids). Omítelos para valores predeterminados razonables.
• Solo lectura: todas las herramientas solo leen datos — no hay herramientas de escritura.
• Descubrimiento primero: llama a tools/list para ver los nombres exactos de las herramientas y los esquemas de argumentos antes de llamar.
• Paginación y filtros: se pasan dentro de arguments según el esquema de cada herramienta (p. ej. rangos de fechas, tamaño de página).
• Registros individuales: las herramientas *.get toman un argumento id y devuelven una sola entidad; las herramientas *.list devuelven colecciones.
• Respuesta: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — analiza content[].text como JSON.

Forma de error

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Códigos de error comunes: -32700 (error de análisis), -32600 (solicitud inválida), -32601 (método no encontrado), -32000 (fallo de la API superior).
• El campo data.status refleja el código de estado HTTP de la API superior de Flowtly cuando está disponible.

Notas

• allowPrefixes permite que resources/read acepte URIs que empiecen con prefijos permitidos.
• Referencia tipo OpenAPI disponible en public/mcp/openapi.json.
• Contratos de intención LLM: Patrones de enrutador + gestor documentados en docs/llm-intent-architecture.md, implementados en packages/agent/src/intents/contract.ts.
• Paginación: Los valores predeterminados se aplican automáticamente por espacio de nombres. Anule con parámetros de consulta explícitos cuando sea necesario.

Herramientas por espacio de nombres