Conecta tu agente

El servidor MCP de Open Factura funciona con cualquier cliente MCP. Hay dos formas de conectarlo:

• Remota (HTTP): https://openfactura.co/mcp con el encabezado Authorization: Bearer of_test_…. No instalas nada.
• Local (stdio): npx -y @openfactura/cli mcp. Usa la clave que guardaste con openfactura login (o las variables OPENFACTURA_API_KEY y OPENFACTURA_URL). Sirve para clientes que no envían encabezados.

Mientras pruebas, usa una clave of_test_…: nada de lo que emitas tiene valor fiscal. La clave decide qué puede hacer el agente; ve Autenticación y claves y las herramientas disponibles en Servidor MCP.

La forma más rápida

npx @openfactura/cli login --url https://app.openfactura.co   # pide la clave sin mostrarla
npx @openfactura/cli mcp install cursor                   # un agente
npx @openfactura/cli mcp install --todos                  # todos los que encuentre en tu equipo
npx @openfactura/cli mcp install cursor --imprimir        # sólo muestra la configuración

Agentes admitidos: claude-code, claude-desktop, cursor, vscode, windsurf, codex, gemini, zed, cline y goose. Con npx @openfactura/cli mcp agentes ves cuáles detecta en tu equipo. Antes de escribir, la CLI guarda una copia de respaldo del archivo de configuración, y nunca elimina los otros servidores que ya tengas.

Configuración manual

Reemplaza of_test_... por tu clave. Después de editar un archivo, reinicia el agente o recarga sus servidores MCP.

Claude Code

Remoto:

claude mcp add --transport http openfactura https://openfactura.co/mcp \
  --header "Authorization: Bearer of_test_..."

Local (stdio), con la clave de openfactura login:

claude mcp add --transport stdio openfactura -- npx -y @openfactura/cli mcp

Añade --scope user para tenerlo en todos tus proyectos o --scope project para compartirlo en el .mcp.json del repositorio. Más detalles en la documentación de Claude Code.

Claude Desktop

Claude Desktop usa el servidor local. Abre Settings → Developer → Edit Config, o edita claude_desktop_config.json:

Sistema	Archivo
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openfactura": {
      "command": "npx",
      "args": ["-y", "@openfactura/cli", "mcp"],
      "env": {
        "OPENFACTURA_API_KEY": "of_test_...",
        "OPENFACTURA_URL": "https://app.openfactura.co"
      }
    }
  }
}

Si ya ejecutaste openfactura login en ese equipo puedes omitir env. Cierra Claude Desktop por completo y vuelve a abrirlo.

Cursor

En un clic (después reemplaza of_test_TU_CLAVE por tu clave en mcp.json):

Instalar en Cursor

O a mano, en ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (sólo uno):

{
  "mcpServers": {
    "openfactura": {
      "url": "https://openfactura.co/mcp",
      "headers": { "Authorization": "Bearer ${env:OPENFACTURA_API_KEY}" }
    }
  }
}

Cursor sustituye ${env:OPENFACTURA_API_KEY} por esa variable de entorno, así la clave no queda en el archivo. También puedes escribir la clave directamente. Ve la documentación de Cursor.

VS Code

En un clic (después reemplaza of_test_TU_CLAVE por tu clave en mcp.json):

Instalar en VS Code

O a mano, en .vscode/mcp.json de tu proyecto (o en el mcp.json de tu perfil de usuario). Con inputs, VS Code te pide la clave la primera vez y la guarda de forma segura:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "openfactura-key",
      "description": "Clave de API de Open Factura (of_test_…)",
      "password": true
    }
  ],
  "servers": {
    "openfactura": {
      "type": "http",
      "url": "https://openfactura.co/mcp",
      "headers": { "Authorization": "Bearer ${input:openfactura-key}" }
    }
  }
}

Ve la referencia de configuración MCP de VS Code.

Windsurf

Abre el archivo mcp_config.json desde el panel MCP de Cascade y añade:

{
  "mcpServers": {
    "openfactura": {
      "serverUrl": "https://openfactura.co/mcp",
      "headers": { "Authorization": "Bearer ${env:OPENFACTURA_API_KEY}" }
    }
  }
}

La ubicación del archivo cambió entre versiones (~/.codeium/windsurf/mcp_config.json en las anteriores); consulta la documentación de Windsurf.

Codex CLI

En ~/.codex/config.toml:

[mcp_servers.openfactura]
url = "https://openfactura.co/mcp"
bearer_token_env_var = "OPENFACTURA_API_KEY"

Codex envía el contenido de OPENFACTURA_API_KEY como Authorization: Bearer …. Para el servidor local:

codex mcp add openfactura -- npx -y @openfactura/cli mcp

Ve la documentación de Codex.

Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer of_test_..." \
  openfactura https://openfactura.co/mcp

O en ~/.gemini/settings.json (todos los proyectos) o .gemini/settings.json (sólo uno):

{
  "mcpServers": {
    "openfactura": {
      "httpUrl": "https://openfactura.co/mcp",
      "headers": { "Authorization": "Bearer of_test_..." }
    }
  }
}

Usa httpUrl (Streamable HTTP), no url, que en Gemini CLI significa SSE. Ve la documentación de Gemini CLI.

Zed

Abre tu configuración con la acción zed: open settings file y añade:

{
  "context_servers": {
    "openfactura": {
      "url": "https://openfactura.co/mcp",
      "headers": { "Authorization": "Bearer of_test_..." }
    }
  }
}

Ve la documentación de Zed.

ChatGPT y claude.ai (web)

ChatGPT y claude.ai en el navegador se conectan a servidores MCP mediante conectores que exigen OAuth. El servidor de Open Factura todavía sólo acepta claves de API; el inicio de sesión con OAuth llegará pronto. Mientras tanto, usa Claude Code, Claude Desktop, Cursor, VS Code u otro de los agentes de esta página.

Enseña a tu agente a facturar

Las habilidades para agentes le enseñan a validar antes de emitir, a confirmar contigo y a manejar los errores:

npx skills add xaviigna/openfactura