Servidor MCP

@qcobro/mcp es un servidor Model Context Protocol para la API de QCobro. Envuelve el mismo @qcobro/sdk que usarías desde tu propio código, así que un cliente MCP (Claude Desktop u otro host compatible) puede listar, crear y gestionar carteras en tu nombre, con la misma autenticación por API key de workspace que ya usa el SDK.

Diagrama: Claude Desktop llama por MCP a @qcobro/mcp, que valida la API key de workspace y delega en @qcobro/sdk, el cual llama a la misma API HTTPS que usa la consola. — @qcobro/mcp envuelve @qcobro/sdk para que un cliente MCP como Claude Desktop gestione QCobro directamente.

Esta primera versión cubre el recurso de carteras, el mismo que el SDK envuelve hoy. Más herramientas llegan a medida que el SDK cubra más recursos.

Antes de empezar

Necesitas una API key de workspace: un accessKeyId y un accessKeySecret, creados desde la página de API Keys de la consola de QCobro. El rol de esa key controla por completo lo que el servidor puede hacer: crea una key con la que te sientas cómodo dejando actuar a un agente, especialmente si vas a habilitar operaciones de escritura como crear o eliminar carteras.

Configura Claude Desktop con la CLI

Instala la CLI de QCobro y usa mcp:configure para que escriba la configuración por ti.

npm install --global @qcobro/ctl

qcobro mcp:configure \
  --access-key-id <accessKeyId> \
  --access-key-secret <accessKeySecret> \
  --workspace <workspaceAccessKeyId>

Este comando escribe (o combina con lo existente) el archivo claude_desktop_config.json de Claude Desktop, añadiendo una entrada qcobro. Reinicia Claude Desktop después de ejecutarlo. Pasa --url si necesitas apuntar a un endpoint distinto del predeterminado (https://api.qcobro.com). Si ya iniciaste sesión con qcobro workspaces:login, puedes omitir los tres flags y mcp:configure usará tu workspace activo.

El comando conserva cualquier otro servidor MCP que ya tengas configurado (por ejemplo @fonoster/mcp): solo añade o reemplaza la entrada qcobro.

Si prefieres no instalar la CLI, edita claude_desktop_config.json tú mismo con la configuración manual de la siguiente sección.

Configuración manual

Si prefieres editar el archivo tú mismo, añade esto a claude_desktop_config.json:

{
  "mcpServers": {
    "qcobro": {
      "command": "npx",
      "args": ["-y", "@qcobro/mcp@latest"],
      "env": {
        "QCOBRO_ENDPOINT": "https://api.qcobro.com",
        "QCOBRO_ACCESS_KEY_ID": "APvsqbjfxua7zvbupqvd8hfy72hix4b7mv",
        "QCOBRO_ACCESS_KEY_SECRET": "<tu-access-key-secret>",
        "QCOBRO_WORKSPACE": "WO6ueex0qan9ojhf820wgiae3qi5luy08y"
      }
    }
  }
}

Variable	Descripción	Obligatoria
`QCOBRO_ACCESS_KEY_ID`	Id de la API key de workspace	Sí
`QCOBRO_ACCESS_KEY_SECRET`	Secreto de la API key de workspace	Sí
`QCOBRO_WORKSPACE`	Workspace en el que actuar (su `accessKeyId`)	Sí
`QCOBRO_ENDPOINT`	URL base de la API (por defecto `https://api.qcobro.com`)	No

Son las mismas credenciales que loginWithApiKey y useWorkspace del SDK: el servidor no hace más que autenticarse con ellas y delegar cada llamada al SDK.

El accessKeySecret se muestra una sola vez al crear la API key. Guárdalo en un gestor de secretos; nunca lo compartas fuera de tu configuración local de Claude Desktop.

Herramientas disponibles

Herramienta	Descripción
`portfolios_list`	Lista las carteras del workspace activo. Entrada opcional: `includeArchived`.
`portfolios_get`	Obtiene una cartera por `id`.
`portfolios_create`	Crea una cartera (`name`, `clientId`).
`portfolios_update`	Actualiza una cartera; `archived: true`/`false` archiva o restaura.
`portfolios_delete`	Elimina una cartera por `id`.
`portfolios_list_accounts`	Lista una página de cuentas de una cartera (`portfolioId`, `limit`/`offset` opcionales), con el total.
`portfolios_sync_accounts`	Sincroniza un lote de cuentas en una cartera (`portfolioId`, `mode`: `APPEND_ONLY` \| `UPDATE_EXISTING` \| `REPLACE`, `rows`).

Cada herramienta valida su entrada contra el mismo esquema que ya valida el método del SDK al que delega: no hay reglas paralelas que puedan desincronizarse. Una entrada inválida se rechaza antes de que cualquier petición llegue a la API de QCobro.

Solución de problemas

Si una llamada a una herramienta falla con un error de autenticación, comprueba que:

QCOBRO_ACCESS_KEY_ID/QCOBRO_ACCESS_KEY_SECRET son un par de API key válido y no expirado.
QCOBRO_WORKSPACE es el accessKeyId de un workspace al que esa key pertenece.
El rol de la key permite la operación que estás llamando. Una key de solo lectura rechazará portfolios_create, por ejemplo.

Siguientes pasos

Visión general del SDK

El cliente TypeScript que @qcobro/mcp envuelve por dentro.

Gestionar carteras

El detalle de cada operación de carteras, desde el lado del SDK.

Get started

Operator guides

SDK

MCP

CLI

API reference

Concepts

Antes de empezar

Configura Claude Desktop con la CLI

Configuración manual

Herramientas disponibles

Solución de problemas

Siguientes pasos

Visión general del SDK

Gestionar carteras

​Antes de empezar

​Configura Claude Desktop con la CLI

​Configuración manual

​Herramientas disponibles

​Solución de problemas

​Siguientes pasos

Visión general del SDK

Gestionar carteras

Antes de empezar

Configura Claude Desktop con la CLI

Configuración manual

Herramientas disponibles

Solución de problemas

Siguientes pasos