VisibilIA MCP Server — pregunta a Claude por tu visibilidad en IA

1. Qué es el MCP de VisibilIA

El Model Context Protocol (MCP) es un estándar abierto creado por Anthropic en 2024 que permite a clientes de IA (Claude Desktop, Cline, Cursor MCP) llamar a herramientas externas en tiempo real.

visibilia-mcp es un servidor MCP que expone 5 herramientas para consultar tu cuenta de VisibilIA desde Claude. En lugar de abrir el dashboard, le preguntas a Claude:

“¿Cómo va mi visibilidad esta semana? ¿He perdido share-of-voice frente a algún competidor?”

Y Claude llama al MCP server, lee tus datos vía la API REST de VisibilIA con tu Bearer token, y responde con números reales.

Arquitectura

Claude Desktop
   ↓ (stdio)
visibilia-mcp (proceso local)
   ↓ (HTTPS + Bearer)
visibilia.app/api/v1/*
   ↓ (Postgres RLS por org_id)
tus datos

2. Requisitos

✓Plan Starter (€49/mes) o Pro (€149/mes) — el plan Free no incluye acceso API. Ver planes.
✓Node.js 20+ instalado en tu máquina (Claude Desktop lo invoca via npx).
✓Un cliente MCP: Claude Desktop (descargar), Cline (VSCode), Cursor MCP, o cualquier otro que soporte stdio MCP servers.
✓Una API key generada en /app/settings/api.

3. Setup paso a paso

Genera tu API key

Inicia sesión y ve a Settings → API. Pulsa Generar API key, ponle un nombre descriptivo (ej. Claude Desktop laptop) y copia el secreto AHORA — no podremos mostrártelo de nuevo. Empieza por vsk_live_.

Localiza el config de tu cliente MCP

Claude Desktop:

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

Cline (VSCode): Settings → MCP Servers → Edit Config.

Cursor: Settings → MCP → Add Server.

Pega esta configuración

{
  "mcpServers": {
    "visibilia": {
      "command": "npx",
      "args": ["-y", "visibilia-mcp"],
      "env": {
        "VISIBILIA_API_KEY": "vsk_live_TU_KEY_AQUI"
      }
    }
  }
}

Sustituye vsk_live_TU_KEY_AQUI por la key que copiaste en el paso 1.

Reinicia el cliente

Cierra y abre Claude Desktop (o reload window en Cline / Cursor). La primera vez, npx -y descarga el paquete en background (~5-10s). Verás un nuevo set de tools con prefijo visibilia_* en el selector.

Pruébalo

Escribe en Claude:

“Lista mis intents en VisibilIA”

Claude pedirá permiso para llamar a la herramienta visibilia_list_intents, lo apruebas, y ves tus datos.

4. Las 5 herramientas

visibilia_get_brand_visibility

Scores de mención, share of voice, sentiment, citación y composite por LLM, en una ventana de fechas. Tu KPI número 1.

visibilia_list_intents

Tus intents (topics) trackeados. Cada uno tiene N prompts que se ejecutan en los 4 motores de IA.

visibilia_list_top_cited_sources

Top dominios que los LLMs citan al hablar de tu sector. Te dice dónde necesitas presencia (Reddit, YouTube, blog tal…).

visibilia_list_recent_mentions

Últimas menciones detectadas con sentiment, posición y URLs citadas. Útil para ver el qué se dice de ti.

visibilia_compare_with_competitor

Tu share of voice vs un competidor concreto en los últimos 7 días, por LLM.

5. Ejemplos de prompts reales

“Resúmeme en 3 bullets cómo ha ido mi visibilidad de marca esta semana”

Llama get_brand_visibility(from=hace 7 días) y devuelve un resumen ejecutivo.

“¿Qué webs cita la IA más a menudo cuando habla de mi sector?”

Llama list_top_cited_sources con group_by=domain. Útil para decisiones de outreach / link-building.

“¿En qué prompts aparece mi competidor X pero no yo?”

Combina list_intents + list_recent_mentions filtrando por competitor_id. Claude razona sobre el cruce.

“Genera un brief para el equipo de contenido: las 5 áreas donde más invisibles estamos”

Pide a Claude que use get_brand_visibility + list_intents y produzca un docto accionable.

“¿Cómo está mi sentiment en Perplexity vs ChatGPT esta semana?”

get_brand_visibility devuelve el desglose por LLM con sentiment_score; Claude lo compara y narra el delta.

6. Multi-marca

Si tienes plan Starter o Pro con varias marcas, cada API key está atada a una organización (la marca activa cuando generaste la key). Para consultar varias marcas desde el mismo Claude Desktop, crea varias keys y varias entradas en el config:

{
  "mcpServers": {
    "visibilia-acme":   { "command": "npx", "args": ["-y", "visibilia-mcp"],
                          "env": { "VISIBILIA_API_KEY": "vsk_live_acme..." } },
    "visibilia-cliente-b": { "command": "npx", "args": ["-y", "visibilia-mcp"],
                             "env": { "VISIBILIA_API_KEY": "vsk_live_b..." } }
  }
}

Para crear una key de otra marca, ve a la sidebar → selector de marcas → activa la otra marca → genera la key desde /app/settings/api.

7. Troubleshooting

Claude Desktop no detecta el server

Asegúrate de haber reiniciado Claude Desktop (no basta con cerrar la ventana — quítalo desde el icono de la barra). Verifica que el JSON es válido (sin comas finales) y que Node 20+ está instalado: ejecuta `node --version` en una terminal.

Tools devuelven '401 — API key inválida o revocada'

Tu key se revocó o nunca llegó a guardarse bien. Genera una nueva en /app/settings/api y reemplaza VISIBILIA_API_KEY en el config. Reinicia Claude Desktop.

'Rate limit excedido'

60 req/min en Starter, 240 req/min en Pro. Suele pasar si Claude itera muchas veces sobre la misma tool. Espera 1 minuto o actualiza a Pro.

'VISIBILIA_API_KEY no configurada'

El bloque `env` se ha quedado mal en el config. Asegúrate de que VISIBILIA_API_KEY está dentro de `env` y empieza por vsk_live_.

No quiero depender de npm — ¿puedo correrlo desde el repo?

Sí. Clona el repo, cd mcp-server && pnpm install && pnpm build, y apunta el config a node /ruta/absoluta/dist/index.js en lugar de npx -y visibilia-mcp.

8. FAQ

¿Mi API key viaja a algún sitio que no sea VisibilIA?

No. El paquete visibilia-mcp solo hace requests a visibilia.app/api/v1/*. Es MIT y el código está en github.com/JpegzaCreate/visibilia/tree/main/mcp-server — puedes auditarlo.

¿Funciona con ChatGPT?

No de momento — ChatGPT no soporta MCP nativamente (a fecha actual). Apple Intelligence y Claude.ai web tampoco. Sí funciona con Claude Desktop, Cline (VSCode), Cursor y cualquier otro cliente que implemente el spec MCP.

¿Qué consume del rate limit de la API?

Cada llamada del MCP es 1 request contra /api/v1/*. Una pregunta que invoque 2 tools cuenta como 2 requests.

¿Puedo escribir (crear intents, lanzar scans) desde el MCP?

No, v0.1 es solo lectura. v0.2 añadirá tools de escritura (trigger_scan, set_alert_rule). Si lo necesitas ahora, dímelo y aceleramos.

¿Self-hosted?

Sí: define VISIBILIA_API_BASE=https://visibilia.midominio.com en el bloque env del config. El MCP usa esa URL en lugar de visibilia.app.

Empieza en 2 minutos

Necesitas plan Starter o Pro para tener API key. Free no incluye acceso a la API.

Empezar gratis Tengo cuenta — ir a generar key

Pregúntale a Claude por tu visibilidad en IA