Quickstart MCP - CUCU API

Prerequisitos

Antes de comenzar, asegurate de tener:

API Key de CUCU — Activa tu plan en app.cucu.bo para obtener tu API Key. Las keys sandbox comienzan con sk_test_ y conectan al SIAT piloto (sin efecto fiscal real).
Un cliente MCP compatible — Claude Desktop, Cursor, Windsurf, VS Code con GitHub Copilot, o Claude Code CLI.
Conexion a internet — El MCP Server corre en la nube, no requiere instalacion local ni Docker.

Configura tu cliente

Selecciona tu editor o cliente AI y sigue las instrucciones. La configuracion toma menos de 2 minutos.

Claude Desktop
Cursor
Windsurf
VS Code
Claude Code

Claude Desktop tiene soporte nativo para MCP con Streamable HTTP.

Abre la configuracion MCP

Ve a Settings (icono de engranaje) → Developer → Edit Config.Esto abrira el archivo claude_desktop_config.json en tu editor de texto.

Agrega el servidor CUCU

Pega la siguiente configuracion en el archivo:

claude_desktop_config.json

{
  "mcpServers": {
    "cucu-facturacion": {
      "url": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Reemplaza YOUR_API_KEY con tu propia key obtenida en app.cucu.bo.

Reinicia Claude Desktop

Cierra y vuelve a abrir Claude Desktop. Veras el icono de herramientas (martillo) en la barra de chat indicando que el MCP Server esta conectado.

En macOS el archivo de configuracion se encuentra en: ~/Library/Application Support/Claude/claude_desktop_config.jsonEn Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor soporta MCP Servers nativamente desde su panel de configuracion.

Abre la configuracion MCP

Ve a Settings (Ctrl/Cmd + ,) → busca MCP en la barra de busqueda → haz clic en Add new MCP server.

Configura el servidor

Agrega la siguiente configuracion:

.cursor/mcp.json

{
  "mcpServers": {
    "cucu-facturacion": {
      "url": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Verifica la conexion

En el panel de MCP deberas ver cucu-facturacion con estado verde (connected). Si aparece en rojo, revisa la seccion de troubleshooting.

Tambien puedes crear el archivo .cursor/mcp.json en la raiz de tu proyecto para que la configuracion sea especifica de ese workspace.

Windsurf usa un archivo de configuracion global para MCP Servers.

Crea o edita el archivo de configuracion

Abre o crea el archivo ~/.windsurf/mcp_config.json:

~/.windsurf/mcp_config.json

{
  "mcpServers": {
    "cucu-facturacion": {
      "serverUrl": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf usa serverUrl en lugar de url. Asegurate de usar la propiedad correcta.

Reinicia Windsurf

Cierra y vuelve a abrir Windsurf para que detecte el nuevo servidor MCP.

Confirma en Cascade

Abre Cascade (el panel AI de Windsurf) y verifica que las herramientas de CUCU aparezcan disponibles.

VS Code soporta MCP a traves de GitHub Copilot (modo agente) y extensiones compatibles.

Crea el archivo de configuracion

En la raiz de tu proyecto, crea el archivo .vscode/mcp.json:

.vscode/mcp.json

{
  "servers": {
    "cucu-facturacion": {
      "type": "http",
      "url": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

El formato de VS Code usa servers (no mcpServers) y requiere "type": "http". Es ligeramente diferente a los demas clientes.

Activa el modo agente en Copilot

Abre el chat de GitHub Copilot y cambia al modo Agent (icono de herramientas). Las herramientas MCP solo estan disponibles en modo agente, no en modo chat normal.

Verifica las herramientas

En el modo agente, haz clic en el icono de herramientas para ver la lista. Deberas ver las 14 herramientas de CUCU disponibles.

Si usas VS Code Insiders, MCP tiene mejor soporte y actualizaciones mas frecuentes. Puedes instalar ambas versiones en paralelo.

Claude Code (CLI) soporta MCP Servers via archivo de configuracion por proyecto.

Crea el archivo de configuracion

En la raiz de tu proyecto, crea o edita .mcp.json:

.mcp.json

{
  "mcpServers": {
    "cucu-facturacion": {
      "type": "url",
      "url": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Inicia Claude Code

Ejecuta claude en tu terminal desde el directorio del proyecto. Claude Code detectara automaticamente el archivo .mcp.json y conectara al servidor.

cd tu-proyecto
claude

Verifica con /mcp

Dentro de Claude Code, ejecuta el comando /mcp para ver los servidores conectados y sus herramientas disponibles.

Claude Code tambien soporta configuracion global en ~/.claude/mcp.json si quieres que el servidor este disponible en todos tus proyectos.

Verificar la conexion

Una vez configurado tu cliente, verifica que todo funciona correctamente:

Prueba una herramienta simple

Pidele a tu AI:

Usa la herramienta verificarFormatoNit para verificar el NIT 1023456789

Deberas recibir una respuesta confirmando que el NIT es valido.

Prueba una consulta

Ahora prueba una herramienta que consulta datos:

Lista las ultimas 3 facturas emitidas

El AI usara listarFacturas y te mostrara los resultados.

Prueba la normativa (RAG)

Verifica que el asistente AI con RAG funciona:

Que requisitos necesita una factura electronica en Bolivia?

El AI usara buscarNormativa para responder con informacion de la base de conocimiento.

Que sigue?

Referencia de Tools

Documentacion detallada de las 14 herramientas: parametros, schemas y ejemplos.

Avanzado

Produccion, dual environments, troubleshooting y clientes custom.

API REST

Si prefieres integracion REST tradicional, consulta la referencia completa.

MCP Server

Documentation Index

​Prerequisitos

​Configura tu cliente

​Verificar la conexion

​Que sigue?

Referencia de Tools

Avanzado

API REST

Prerequisitos

Configura tu cliente

Verificar la conexion

Que sigue?