> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart MCP

> Conecta tu editor o AI al MCP Server de CUCU en 2 minutos. Paso a paso para Claude Desktop, Cursor, Windsurf, VS Code y Claude Code.

## Prerequisitos

<Note>
  Antes de comenzar, asegurate de tener:

  * **API Key de CUCU** — Activa tu plan en [app.cucu.bo](https://app.cucu.bo/signup) 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.
</Note>

***

## Configura tu cliente

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

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop tiene soporte nativo para MCP con Streamable HTTP.

    <Steps>
      <Step title="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.
      </Step>

      <Step title="Agrega el servidor CUCU">
        Pega la siguiente configuracion en el archivo:

        ```json claude_desktop_config.json theme={"system"}
        {
          "mcpServers": {
            "cucu-facturacion": {
              "url": "https://sandbox.cucu.bo/mcp",
              "headers": {
                "X-API-Key": "YOUR_API_KEY"
              }
            }
          }
        }
        ```

        <Warning>
          Reemplaza `YOUR_API_KEY` con **tu propia key** obtenida en [app.cucu.bo](https://app.cucu.bo/signup).
        </Warning>
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    <Tip>
      En macOS el archivo de configuracion se encuentra en:
      `~/Library/Application Support/Claude/claude_desktop_config.json`

      En Windows:
      `%APPDATA%\Claude\claude_desktop_config.json`
    </Tip>
  </Tab>

  <Tab title="Cursor">
    Cursor soporta MCP Servers nativamente desde su panel de configuracion.

    <Steps>
      <Step title="Abre la configuracion MCP">
        Ve a **Settings** (Ctrl/Cmd + ,) → busca **MCP** en la barra de busqueda → haz clic en **Add new MCP server**.
      </Step>

      <Step title="Configura el servidor">
        Agrega la siguiente configuracion:

        ```json .cursor/mcp.json theme={"system"}
        {
          "mcpServers": {
            "cucu-facturacion": {
              "url": "https://sandbox.cucu.bo/mcp",
              "headers": {
                "X-API-Key": "YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="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](/mcp/advanced#troubleshooting).
      </Step>
    </Steps>

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

  <Tab title="Windsurf">
    Windsurf usa un archivo de configuracion global para MCP Servers.

    <Steps>
      <Step title="Crea o edita el archivo de configuracion">
        Abre o crea el archivo `~/.windsurf/mcp_config.json`:

        ```json ~/.windsurf/mcp_config.json theme={"system"}
        {
          "mcpServers": {
            "cucu-facturacion": {
              "serverUrl": "https://sandbox.cucu.bo/mcp",
              "headers": {
                "X-API-Key": "YOUR_API_KEY"
              }
            }
          }
        }
        ```

        <Note>
          Windsurf usa `serverUrl` en lugar de `url`. Asegurate de usar la propiedad correcta.
        </Note>
      </Step>

      <Step title="Reinicia Windsurf">
        Cierra y vuelve a abrir Windsurf para que detecte el nuevo servidor MCP.
      </Step>

      <Step title="Confirma en Cascade">
        Abre Cascade (el panel AI de Windsurf) y verifica que las herramientas de
        CUCU aparezcan disponibles.
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code">
    VS Code soporta MCP a traves de GitHub Copilot (modo agente) y extensiones compatibles.

    <Steps>
      <Step title="Crea el archivo de configuracion">
        En la raiz de tu proyecto, crea el archivo `.vscode/mcp.json`:

        ```json .vscode/mcp.json theme={"system"}
        {
          "servers": {
            "cucu-facturacion": {
              "type": "http",
              "url": "https://sandbox.cucu.bo/mcp",
              "headers": {
                "X-API-Key": "YOUR_API_KEY"
              }
            }
          }
        }
        ```

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

      <Step title="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.
      </Step>

      <Step title="Verifica las herramientas">
        En el modo agente, haz clic en el icono de herramientas para ver la lista.
        Deberas ver las 40 herramientas de CUCU disponibles.
      </Step>
    </Steps>

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

  <Tab title="Claude Code">
    Claude Code (CLI) soporta MCP Servers via archivo de configuracion por proyecto.

    <Steps>
      <Step title="Crea el archivo de configuracion">
        En la raiz de tu proyecto, crea o edita `.mcp.json`:

        ```json .mcp.json theme={"system"}
        {
          "mcpServers": {
            "cucu-facturacion": {
              "type": "url",
              "url": "https://sandbox.cucu.bo/mcp",
              "headers": {
                "X-API-Key": "YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="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.

        ```bash theme={"system"}
        cd tu-proyecto
        claude
        ```
      </Step>

      <Step title="Verifica con /mcp">
        Dentro de Claude Code, ejecuta el comando `/mcp` para ver los servidores
        conectados y sus herramientas disponibles.
      </Step>
    </Steps>

    <Tip>
      Claude Code tambien soporta configuracion global en `~/.claude/mcp.json`
      si quieres que el servidor este disponible en todos tus proyectos.
    </Tip>
  </Tab>
</Tabs>

***

## Verificar la conexion

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Que sigue?

<CardGroup cols={3}>
  <Card title="Referencia de Tools" icon="wrench" href="/mcp/tools">
    Documentacion detallada de las 40 herramientas: parametros, schemas y ejemplos.
  </Card>

  <Card title="Avanzado" icon="gear" href="/mcp/advanced">
    Produccion, dual environments, troubleshooting y clientes custom.
  </Card>

  <Card title="API REST" icon="code" href="/api/overview">
    Si prefieres integracion REST tradicional, consulta la referencia completa.
  </Card>
</CardGroup>