MCP ActiveView (read-only)

Servidor MCP que expone la ActiveView External API (https://external-api.activeview.app) a Claude. Es un wrapper de solo lectura: el helper de red solo hace GET, así que ninguna tool puede crear, modificar ni borrar datos.

Hecho con FastMCP (Python), transporte stdio (local).

---

Qué expone (12 tools, todas de lectura)

Price rules

• get_price_rules — reglas de precio de un sitio.

Reportes por dominio

• get_report_by_domain — métricas (revenue, impressions, eCPM, match rate…).
• get_kvp_report_by_domain — métricas agrupadas por una key de GAM.
• get_session_kvp_report_by_domain — KVP de sesiones (Snowflake).
• get_custom_gam_report_by_domain — reporte GAM con dimensiones/métricas a elección.

Reportes por network (varios dominios con el filtro domains)

• get_report_by_network
• get_kvp_report_by_network
• get_custom_gam_report_by_network

Redirects (A/B testing)

• list_redirect_domains — dominios de redirect con sus paths.
• get_redirect_path — detalle de un path.
• get_redirect_path_mappings — split de tráfico (url + %).
• get_redirect_path_mapping_logs — historial de cambios del split.

💰 Micros: los campos de revenue de GAM (*_revenue) vienen en micros (1.000.000 = 1 unidad de moneda). Divídelos entre 1.000.000. Las tools ya se lo recuerdan a Claude en su descripción.

---

Requisitos

• Python ≥ 3.10 (recomendado 3.12). El Python 3.9 que trae macOS por defecto no sirve.
• git para clonar.
• Una API key de ActiveView, en formato token:secret (el bearer completo, con los dos puntos).
• Opcional pero recomendado: uv (instala con brew install uv). Si no quieres uv, abajo tienes la variante con python -m venv + pip.

---

Instalación paso a paso (Claude Code)

1. Clonar el repo

git clone https://github.com/TU-USUARIO/mcp-activeview.git
cd mcp-activeview

2. Crear el entorno virtual e instalar dependencias

Con uv (recomendado):

uv venv --python 3.12 .venv
uv pip install --python .venv -r requirements.txt

O con venv + pip estándar (sin uv):

python3.12 -m venv .venv        # o python3 si tu 3 ya es ≥3.10
./.venv/bin/pip install -r requirements.txt

3. Conseguir tu API key

La sacas de tu panel de ActiveView. Es un único valor con la forma token:secret: dos partes separadas por dos puntos (:). Lo copias entero, incluidos los dos puntos. Por ejemplo:

# Ejemplo (valores inventados). Pega tu clave real entera:
ACTIVEVIEW_API_KEY=ab12cd34ef56...:9f8e7d6c...

En esta guía verás el placeholder tu_token:tu_secret; sustitúyelo por tu clave real.

Cada persona usa su propia key. La key nunca va dentro del repo.

4. Registrar el servidor en Claude Code

Desde la carpeta del repo (para que $(pwd) resuelva las rutas absolutas solo):

claude mcp add activeview \
  --scope user \
  --env ACTIVEVIEW_API_KEY=tu_token:tu_secret \
  --env ACTIVEVIEW_NETWORK_CODE=YOUR_NETWORK_CODE \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

• --scope user lo deja disponible en todos tus proyectos. Usa --scope local (por defecto) si solo lo quieres en el proyecto actual.
• ACTIVEVIEW_NETWORK_CODE es opcional: si lo pones, podrás pedir reportes sin repetir el network code en cada consulta (ver sección abajo). Quítalo si no quieres un valor por defecto.

5. Verificar

claude mcp list

Debe mostrar activeview: … ✔ Connected. Luego, dentro de Claude Code, pídele algo como:

"Dame las impresiones de ayer en tu-dominio.com"

Si responde con datos, está funcionando.

---

Network code por defecto (opcional)

Puedes fijar un network_code por defecto con ACTIVEVIEW_NETWORK_CODE. Si lo haces, las tools se pueden llamar sin pasar network_code cada vez; un valor explícito en la llamada siempre tiene prioridad sobre el por defecto.

Funciona tanto por --env (paso 4) como en un fichero .env local:

cp .env.example .env
# edita .env:
#   ACTIVEVIEW_API_KEY=tu_token:tu_secret
#   ACTIVEVIEW_NETWORK_CODE=YOUR_NETWORK_CODE    # opcional, el de tu propiedad principal

⚠️ Un único network code por defecto solo cubre los dominios de esa red. Para dominios de otra red, pasa su network_code en la consulta.

¿--env o .env? Lo más limpio es --env en claude mcp add (la key vive en la config de Claude, no en el proyecto). El .env es cómodo para pruebas locales y está ignorado por git (no se sube nunca). Si una variable ya viene del cliente MCP, esa gana sobre la del .env.

---

Alternativa: Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "activeview": {
      "command": "/ruta/absoluta/a/mcp-activeview/.venv/bin/python",
      "args": ["/ruta/absoluta/a/mcp-activeview/server.py"],
      "env": {
        "ACTIVEVIEW_API_KEY": "tu_token:tu_secret",
        "ACTIVEVIEW_NETWORK_CODE": "YOUR_NETWORK_CODE"
      }
    }
  }
}

Usar el python del .venv directamente es lo más robusto. Reinicia el cliente tras añadirlo.

---

Probarlo en local (sin Claude)

# Inspector visual de FastMCP (UI web para invocar las tools a mano):
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/fastmcp dev server.py

# O lanzarlo en stdio tal cual lo lanzará Claude:
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/python server.py

---

Seguridad

Este servidor está pensado para ser seguro por diseño:

• Solo lectura, garantizado por construcción. El único helper de red (_get) usa exclusivamente httpx.get. No existe ningún post/put/patch/delete en el código, así que ninguna tool puede crear, modificar ni borrar datos. Todas las tools se anuncian con readOnlyHint: True.
• Host fijo. Todas las peticiones van a https://external-api.activeview.app; el servidor no acepta URLs ni hosts arbitrarios.
• Validación de entradas. network_code debe ser numérico y domain solo admite [A-Za-z0-9.-]. Esto bloquea intentos de inyección de path (../, ?, #, @, /) en la URL de la petición.
• La API key nunca se versiona. .env está en .gitignore; el repo solo trae .env.example con placeholders. La key se pasa por variable de entorno y no se registra en logs.
• Sin ejecución de código ni acceso a disco. El servidor solo hace peticiones HTTP GET de lectura; no escribe ficheros, no ejecuta shell, no toca tu sistema.

Buenas prácticas al instalarlo:

• Trata tu ACTIVEVIEW_API_KEY como una contraseña. Si la pasaste por línea de comandos, recuerda que puede quedar en el historial del shell; preferible .env o un gestor de secretos.
• Si crees que tu key se ha filtrado, rótala en ActiveView; la del repo nunca debería aparecer en un commit.
• Revisa requirements.txt antes de instalar (dependencias: fastmcp, httpx, python-dotenv).

---

Troubleshooting

Síntoma	Causa probable / solución
claude mcp list muestra ✘ Failed to connect	Ruta del python/server.py mal, o venv sin dependencias. Reejecuta el paso 2 y usa rutas absolutas.
Aviso "fastmcp not installed" en VSCode	Selecciona el intérprete .venv/bin/python (Command Palette → "Python: Select Interpreter").
Las tools devuelven 401	API key inválida o revocada. Comprueba ACTIVEVIEW_API_KEY (formato token:secret).
Invalid network_code / Invalid domain	El valor llevaba caracteres no permitidos. network_code es numérico; domain solo letras/dígitos/puntos/guiones.
No network_code given…	No pasaste network_code y no hay ACTIVEVIEW_NETWORK_CODE configurado.
python3.12: command not found	Instala Python 3.12 (brew install python@3.12) o usa otro ≥3.10.

---

Nota sobre los reportes "Custom GAM"

La colección Postman traía las dos variantes con el orden de segmentos distinto (gam/custom vs custom/gam). Confirmado contra la API real, el orden correcto en ambas es gam/custom:

• por dominio → /report/gam/custom/{network}/{domain}
• por network → /report/gam/custom/{network}