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

# Servidor MCP

> Conecta AthenaHQ con ChatGPT, Claude y otros asistentes de IA mediante Model Context Protocol

AthenaHQ ofrece un servidor remoto de [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Una vez conectado, un asistente como Claude o ChatGPT puede consultar en lenguaje natural tus datos de visibilidad en búsquedas con IA (cuota de voz, porcentajes de citas y menciones, posiciones, fuentes citadas, consultas y respuestas en seguimiento, contenido y propuestas) sin que escribas llamadas a la API.

Las conexiones con inicio de sesión (Claude.ai y ChatGPT) respetan los permisos de tu cuenta, con las exclusiones de datos de respuestas de Claude descritas más abajo. Las herramientas de escritura están disponibles en conexiones con clave de API y, en conexiones con sesión iniciada, cuando tu rol tiene el permiso de escritura correspondiente. Cada escritura aplica la misma validación y registro de auditoría que el panel.

**URL del servidor**

```text theme={null}
https://api.athenahq.ai/api/mcp
```

## Etiquetas de fuentes

Utiliza `source_tags__list`, `source_tags__get_sources`, `source_tags__create`,
`source_tags__update` y `source_tags__delete` para trabajar con etiquetas de fuentes.
Un sitio web ve tres tipos: Propia y Competidor (establecidas a partir de los
identificadores de marca y competidores), etiquetas integradas que AthenaHQ
clasifica automáticamente (Medios, Social, Gobierno, Comercio electrónico,
Sitios de reseñas, Agencias de prensa, Academia e investigación y Wiki) y las
etiquetas personalizadas del sitio. Son independientes de las etiquetas de consultas.
Todas las herramientas requieren `website_id` y respetan los ámbitos de sitios web
de la clave o los permisos de Análisis de tu cuenta. Leer requiere acceso de
lectura; escribir requiere acceso de escritura.

`source_tags__list` devuelve cada etiqueta con tipo, icono, color, revisión y
patrones: los propios de una etiqueta personalizada o, en una integrada, solo
lo que este sitio ha añadido o quitado. Nunca lista los patrones de la propia
plataforma. Utiliza `offset` y `limit` para paginar etiquetas, o `tag_id`,
`pattern_offset` y `pattern_limit` para paginar los patrones de una etiqueta.

`source_tags__get_sources` lista dominios citados con recuentos de citas: los
que coinciden con una etiqueta personalizada (`tag_id`) o, con `untagged: true`,
los que no cubre ninguna. No admite etiquetas integradas ni Propia/Competidor
como `tag_id`; en ellas, añade o quita patrones.

`source_tags__update` edita una etiqueta con el `expected_revision` actual.
En una personalizada acepta `name`, `add_patterns` y `remove_patterns` exactos.
En una integrada añade o quita patrones de la copia del sitio: solo acepta
una adición si el patrón no tiene ya la etiqueta aquí, y una eliminación si
la tiene (por regla de la plataforma, clasificación automática o una adición
tuya). Las integradas no pueden renombrarse. `source_tags__create` crea una
personalizada con patrones e icono y color opcionales; los nombres de las
integradas están reservados. `source_tags__delete` elimina una personalizada
y sus asignaciones, pero conserva los registros de fuentes; las integradas
no pueden eliminarse. Los patrones admiten hosts, subárboles (`*.example.com`),
secciones de ruta, páginas exactas y restricciones de consulta; máximo 500 por lista.

Actualizar y eliminar anuncian indicaciones de acción destructiva y piden al
asistente obtener confirmación explícita. Tu cliente MCP controla las solicitudes
de aprobación; estas indicaciones no imponen un diálogo de confirmación. Las
llamadas autorizadas se ejecutan de inmediato. El chat Athena AI conserva sus
tarjetas de aprobación. Si `analytics_refreshed` es falso, la escritura ha
funcionado, pero el análisis filtrado puede seguir en caché; no la repitas para
actualizarlo. Estas herramientas no añaden endpoints REST.

## Contacto

Contacto encuentra autores de páginas que citan las respuestas de IA y redacta
una propuesta para cada uno. Cinco herramientas cubren el mismo trabajo que la página Contacto:

* `list_outreach_contacts` lee contactos guardados: estado, autor, correo y su
  fuente, LinkedIn, página de contacto y borrador. Solo lista páginas que alguien
  haya evaluado, enriquecido o para las que haya redactado; encuentra otras con
  `get_source_pages`. Filtra por `url` o `statuses`; pagina con `offset` y
  `limit` (20 por defecto, máximo 50).
* `find_outreach_author` lee la firma de una página, las direcciones que publica
  y Hunter.io, y guarda el resultado. Si no encuentra autor, guarda cualquier
  dirección o página de contacto del sitio que encuentre en su lugar.
* `draft_outreach_message` redacta una propuesta para una página y la guarda
  como su borrador. Utiliza las instrucciones personalizadas de todo el equipo
  del sitio (configuradas en Contacto), el nombre de autor guardado y el nombre
  del usuario con sesión; las conexiones con clave pueden pasar `sender_name`.
  No se envía nada.
* `update_outreach_contact` edita nombre de autor, correo, LinkedIn, asunto o
  cuerpo. Indica al menos un campo; solo cambian los suministrados y `null`
  borra uno. Cambiar el autor por otra persona también borra correo y LinkedIn
  del anterior, salvo que proporciones otros nuevos.
* `set_outreach_status` mueve hasta 100 páginas a `New`, `Todo`, `In Progress`,
  `Done` o `Rejected` y registra cada cambio de un contacto existente en su
  Actividad. Una página sin contacto recibe uno con el nuevo estado, aún sin
  entrada de Actividad; `New` solo restablece contactos existentes.

Cada correo incluye un `email_source`: `page_author` (publicado en la página y
correspondiente al autor), `page_contact` (dirección del sitio, que quizá no
llegue al autor), `hunter` (coincidencia de Hunter.io no publicada en la página;
compruébala antes de enviar) o `manual`. Es `null` si se desconoce la fuente,
como en correos guardados antes de registrarlas. `page_emails` lista hasta cinco
direcciones publicadas en la página o en su página de contacto enlazada, primero
la elegida, para compararlas con ella; no es un inventario completo.

Las páginas se identifican por `url` en el formato guardado en la lista de
Contacto, como `example.com/blog/post`. Primero se usa un contacto ya guardado
con la URL exacta que pasas, como uno guardado por Contacto para una variante
de consulta que las reglas de URL del sitio listan por separado. En otro caso
se ignoran protocolo, `www.` y cadena de consulta (por ejemplo, parámetros de
seguimiento `utm_`), igual que en Contacto. La página siempre se lee en la URL
que pasas. Todas las herramientas requieren `website_id` y permisos de Contenido:
lectura para listar y escritura para las demás. `find_outreach_author` cuesta
0,1 créditos cuando encuentra autor y `draft_outreach_message`, 0,1 por borrador,
facturados en créditos enteros cada 10 filas completadas correctamente, igual
que en Contacto. No añaden endpoints REST.

## Acceso público de rastreadores de IA

`check_public_ai_access` comprueba un dominio HTTPS público sin cuenta de AthenaHQ.
Pasa `{ "domain": "example.com" }`, sin ruta, credenciales ni puerto personalizado.
La respuesta incluye `evidence` por agente que puede ser nulo, `diagnostics`
de la solicitud y un `log` de diagnóstico. Búsqueda, recuperación por el usuario
y entrenamiento tienen funciones distintas. Google-Extended solo tiene política
y no recibe ninguna comprobación HTTP.

La extensión de ChatGPT se abre desde ubicaciones compatibles de la barra lateral
y las conversaciones. Muestra respuestas HTTP y permisos de robots, restaura
informes de resultados de herramientas, respeta el tema de la aplicación y admite
copiar, exportar y compartir explícitamente informes. Las solicitudes proceden
de AthenaHQ con cadenas de agente de usuario de rastreadores, no IP verificadas
de estos. Las observaciones desconocidas no permiten conclusiones. Estas
comprobaciones no miden visibilidad ni garantizan acceso real, indexación o citas.

Los análisis públicos se limitan a cinco por minuto por IP de entrada resumida
mediante hash. Las solicitudes MCP anónimas tienen otro límite de 60 por minuto
y 512 KiB por solicitud; se rechazan los lotes. El análisis de cuenta y las
escrituras mantienen autenticación, ámbitos y auditoría. La herramienta autenticada
`check_ai_access` y el contrato de socios `POST /v1/ai-access/check` conservan su comportamiento.

Al llamar a una herramienta de cuenta sin credenciales, el servidor devuelve HTTP 401
con `WWW-Authenticate` apuntando a los metadatos OAuth de su recurso. La respuesta
conserva además el desafío `_meta["mcp/www_authenticate"]` a nivel de herramienta.
Tu cliente puede usar cualquiera para iniciar sesión y reintentar la llamada.
La inicialización, descubrimiento de herramientas y herramientas públicas de
rastreadores siguen disponibles sin iniciar sesión.

## Entradas de intervalos de fechas

Las herramientas MCP con `filters.start_date` y `filters.end_date` aceptan:

| Formato | Ejemplos |
| - | - |
| Año primero | `2026-09-29`, `2026/9/29`, `2026.9.29` |
| Nombre del mes en inglés | `September 29, 2026`, `Sep 29 2026`, `29 September 2026`, `29-Sep-2026` |
| Fecha numérica sin ambigüedad | `09/29/2026`, `29/09/2026`, `29-09-2026`, `29.09.2026` |
| Marca de tiempo ISO 8601 | `2026-09-29T12:30:00Z`, `2026-09-29T12:30:00-07:00` |

Las fechas se normalizan antes de consultar. Las entradas de solo fecha conservan
su día natural; las marcas de tiempo conservan su instante y se normalizan a UTC.
Una marca ISO sin zona horaria se interpreta como UTC. Un inicio de solo fecha
empieza a medianoche UTC; un final de solo fecha incluye ese día hasta
`23:59:59.999Z`. Las marcas finales explícitas conservan su instante exacto,
incluida la medianoche. Omitir `end_date` conserva el valor predeterminado de la herramienta.

Fechas no válidas, incompletas, expresiones relativas como `yesterday` y fechas
numéricas ambiguas como `03/04/2026` devuelven un error de validación en vez de
resultados vacíos. Escribe el mes o utiliza `YYYY-MM-DD` para evitar ambigüedad.
Usa años de cuatro cifras. Un final explícito no puede ser anterior al inicio.

Esta flexibilidad se aplica a los filtros de intervalos compartidos de MCP,
incluidos métricas, respuestas, fuentes y análisis de contenido. Las entradas
REST de socios, marcas del registro de actividad y predicados de consultas de
cubos genéricos conservan sus formatos documentados.

## Conectar Claude.ai

Conecta desde la ficha de AthenaHQ en el directorio de conectores de Claude.
No necesitas clave de API. Inicias sesión con tu cuenta de AthenaHQ.

> [!NOTE]
>
> Por política del proveedor, el conector de Claude excluye respuestas individuales
> generadas por Claude y registros a nivel de respuesta derivados de ellas.
> Puedes explorar respuestas de otras plataformas, como ChatGPT. El análisis
> agregado, como totales de visibilidad y métricas de atributos, puede seguir
> incluyendo datos de Claude. Para ver sus respuestas individuales, usa el panel
> de AthenaHQ o la API REST con una [clave de API](https://docs.athenahq.ai/es/api-reference/authentication.md).

En planes Claude Team, un Owner o Primary Owner debe activar el conector para
la organización antes de conectar tu cuenta. En Enterprise, también pueden
activarlo usuarios con un rol personalizado que incluya **Manage access to Libraries**.

**1. Conectar AthenaHQ**

Abre la [ficha del conector de AthenaHQ](https://claude.ai/directory/athenahq)
en Claude y sigue las indicaciones. También está en **Customize > Connectors**.

**2. Iniciar sesión y elegir una organización**

Se te pedirá iniciar sesión con tu cuenta de AthenaHQ y elegir la organización.
Después Claude descubre automáticamente todas las herramientas disponibles.

**3. Preguntar sobre tu rendimiento en búsquedas con IA**

En un chat, abre **+ > Connectors** y activa AthenaHQ para la conversación.
Pregunta, por ejemplo: «Usa AthenaHQ para comparar nuestra cuota de voz con
competidores durante los últimos 30 días». Claude incorpora tus datos de
AthenaHQ a la conversación. Revisa y aprueba las solicitudes de herramientas cuando se te pida.

Prueba preguntas como:

* «¿Qué visibilidad tiene nuestra marca en búsquedas con IA durante los últimos 30 días?»
* «¿Qué dice ChatGPT sobre nuestra marca en las respuestas que seguimos?»
* «¿Qué competidores han ganado cuota de voz durante el último mes?»
* «¿Qué páginas se citan y en cuáles deberíamos centrarnos después?»

> [!NOTE]
>
> ¿Prefieres configurarlo manualmente? En Claude, abre **Customize > Connectors**
> y añade un conector personalizado llamado **AthenaHQ** con la URL
> `https://api.athenahq.ai/api/mcp`. Sigue la autenticación para iniciar sesión
> con tu cuenta y elegir organización. En Team y Enterprise, un Owner o Primary
> Owner debe añadirlo primero; en Enterprise también pueden los usuarios con
> **Manage access to Libraries**. Consulta la
> [guía de conectores personalizados de Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
> para los pasos de tu plan.

## Conectar ChatGPT

Lo más rápido es el plugin oficial de AthenaHQ. No necesitas clave de API.
Inicias sesión con tu cuenta de AthenaHQ.

### ¿Tiene el plugin un coste aparte?

Por parte de AthenaHQ, instalar el plugin es gratuito y no tiene un coste
separado. Utiliza tu cuenta existente y se siguen aplicando los límites normales
del plan a las funciones y acciones que utilizas. Su disponibilidad en ChatGPT
depende de tu plan de OpenAI, configuración del espacio, rol y región.

**1. Instalar el plugin**

Abre la [ficha del plugin de AthenaHQ](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69)
en ChatGPT y pulsa **Install plugin**.

**2. Iniciar sesión y elegir una organización**

Autoriza con tu cuenta de AthenaHQ y elige la organización que quieres conectar.

**3. Mencionar @AthenaHQ en un chat**

Escribe `@AthenaHQ` y tu pregunta, por ejemplo «@AthenaHQ, ¿cómo aparece mi
marca en las búsquedas con IA?», y ChatGPT incorpora tus datos a la conversación.

> [!NOTE]
>
> ¿Prefieres configurarlo manualmente? Puedes añadir el servidor como conector
> MCP personalizado: en **Settings** de ChatGPT, añade uno (en **Apps** o
> **Connectors**, según plan y versión), introduce `https://api.athenahq.ai/api/mcp`
> e inicia sesión con tu cuenta de AthenaHQ. Los conectores personalizados requieren
> un plan compatible (Pro, Business o Enterprise) y quizá activar el modo desarrollador.

## Conectar Optimizely Opal

Necesitas el rol de administrador de Opal para registrar un proveedor MCP remoto.

### Iniciar sesión con OAuth

1. En Opal, abre **Tools > External Providers > Add Remote MCP Provider**.
2. Introduce `https://api.athenahq.ai/api/mcp`, selecciona **OAuth 2.0** y pulsa **Discover OAuth Endpoints**.
3. Deja **Use my own credentials** desactivado para que Opal utilice Dynamic Client Registration. AthenaHQ emite automáticamente un ID de cliente; no necesitas uno emitido de antemano ni un secreto de cliente.
4. Deja los ámbitos vacíos. AthenaHQ no anuncia ámbitos OAuth. No introduzcas los marcadores `your-client-id` ni `scope1,scope2,scope3`.
5. Introduce un nombre de proveedor único y regístralo. Completa las aprobaciones de Opal; conecta desde **Tools > Connectors** e inicia sesión en AthenaHQ para elegir tu organización.
6. Selecciona las herramientas que añadir. Para utilizarlas en Opal Chat, activa **Enable for Chat** en **Tools > Tools**.

### Conectar con una clave de API

Si prefieres una conexión compartida con clave, crea una en la [página de claves de API](https://app.athenahq.ai/settings/api). Limítala a los sitios a los que deba acceder Opal.

1. Registra un proveedor MCP remoto con la misma URL del servidor.
2. Selecciona **Bearer token** y pega la clave de AthenaHQ completa en **Bearer Token**, sin añadir `Bearer`.
3. Completa el registro, añade herramientas y actívalas para el chat según necesites.

Opal envía la clave como `Authorization: Bearer <api-key>`. La conexión utiliza
los permisos de organización y sitio de la clave, incluida escritura en su
ámbito. Elimínala en AthenaHQ para revocar el acceso.

Consulta la [guía de configuración de MCP remoto de Optimizely](https://support.optimizely.com/hc/en-us/articles/47179211028749-Add-a-remote-MCP-provider)
para sus pasos de aprobación de proveedor y herramientas.

## Conectar otros clientes MCP

Los clientes sin flujo de inicio de sesión se autentican con clave de API mediante
`x-api-key: <api-key>` o `Authorization: Bearer <api-key>`. La autenticación de clave
como Bearer se admite en `/api/mcp`; los endpoints REST de `/api/v1` requieren `x-api-key`.

**1. Crear una clave de API**

Ve a la [página de claves de API](https://app.athenahq.ai/settings/api) del panel.
Limítala a sitios concretos si quieres restringir el acceso y guárdala de forma segura.

> [card] [Gestionar claves de API](https://app.athenahq.ai/settings/api)
>
> Crea, consulta y gestiona claves de API en la configuración de tu organización

**2. Añadir el servidor a la configuración del cliente**

Sustituye `your_api_key_here` por tu clave.

```json theme={null}
{
  "mcpServers": {
    "athenahq": {
      "type": "http",
      "url": "https://api.athenahq.ai/api/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add --transport http --scope user athenahq https://api.athenahq.ai/api/mcp \
  --header "x-api-key: your_api_key_here"
```

## Acceso y ámbito

Una conexión MCP ve exactamente lo que autorizan sus credenciales, con el mismo
ámbito que la [API REST](https://docs.athenahq.ai/es/api-reference/authentication.md):

* El acceso a **organización** y **sitios web** sigue al usuario con sesión (Claude.ai) o el ámbito de la clave.
* Una clave limitada a sitios solo accede a ellos. La herramienta de saldo existente `get_credits_organization` también permite que claves limitadas lean el agregado de toda su organización. Las de uso detallado (`get_credit_usage` y `get_credit_usage_events`) requieren una clave global de organización o un usuario con acceso a facturación de organización. Pertenecer solo a un sitio o grupo no basta.
* Las **herramientas de escritura** se registran en conexiones con clave y en conexiones con sesión vinculadas a una organización. Con sesión, cada escritura requiere el permiso de tu rol para su categoría (consulta [Herramientas de escritura](#write-tools)); las claves actúan como administrador dentro de su ámbito. Cada escritura aplica la misma validación y auditoría que el panel.

> [!NOTE]
>
> Solo los administradores de organización pueden crear, editar o eliminar claves.
> Con sesión iniciada, las herramientas siguen tu rol: un lector puede leer todo
> lo siguiente salvo las tres lecturas administrativas de toda la organización
> (`get_groups`, `get_group_detail`, `get_user_by_email`) y las herramientas de uso
> de créditos, que requieren acceso a facturación. Los lectores solo pueden usar
> escrituras abiertas a todos los miembros (como `create_saved_view`).

## Herramientas disponibles

El asistente las descubre automáticamente al conectar. La mayoría corresponde
a un endpoint de la [referencia de la API](https://docs.athenahq.ai/es/api-reference/introduction.md).

### Métricas

| Herramienta | Qué devuelve |
| - | - |
| `get_share_of_voice_cumulative` | Cuota de voz entre competidores para un intervalo de fechas |
| `get_share_of_voice_time_series` | Cuota de voz a lo largo del tiempo (diaria) |
| `get_citation_rate_cumulative` | Porcentaje de citas (frecuencia con la que las respuestas enlazan a tu sitio) entre competidores |
| `get_citation_rate_time_series` | Porcentaje de citas a lo largo del tiempo (diario) |
| `get_mention_rate_cumulative` | Porcentaje de menciones (frecuencia con la que la IA nombra tu marca) entre competidores |
| `get_mention_rate_time_series` | Porcentaje de menciones a lo largo del tiempo (diario) |
| `get_position_cumulative` | Posición media en respuestas de IA para un intervalo |
| `get_position_time_series` | Posición a lo largo del tiempo (diaria) |
| `get_position_distribution` | Proporción de respuestas en las que la marca está arriba, en medio o abajo |
| `get_ai_search_value` | Valor de búsqueda con IA: valor del mercado temático, valor captado, margen de mejora, cobertura y detalle por tema |
| `get_shopping_metrics` | Información de compras: apariciones de productos en respuestas de compra con IA, posiciones, precios y rivales |

### Consultas analíticas

Herramientas flexibles sobre el mismo almacén analítico que utiliza el panel,
para preguntas que no cubren las herramientas de métricas fijas.

| Herramienta | Qué devuelve |
| - | - |
| `query_metrics` | Medidas agregadas (recuento, media, suma, mínimo y máximo) de cualquier cubo, agrupadas por sus dimensiones permitidas, con comparación entre periodos opcional |
| `query_rows` | Filas individuales (texto de respuesta, identificadores y menciones) de cualquier cubo, con paginación por cursor |

### Atributos de marca

Palabras clave de percepción de marca (como «Asequible» o «Soporte lento»)
extraídas de respuestas de IA. La API y los nombres de herramientas las llaman atributos.

| Herramienta | Qué devuelve |
| - | - |
| `get_attributes` | Atributos de marca en seguimiento de un sitio, con sus ID |
| `get_attribute_metrics` | Para cada atributo, cuántas respuestas lo han mencionado en un intervalo |
| `get_competitor_attribute_metrics` | El mismo desglose por competidor en seguimiento |
| `get_attribute_time_series` | Tendencia diaria de un atributo, con marca y competidores en paralelo |
| `get_attribute_observations` | Observaciones individuales de atributos con fragmento de respuesta y puntuación de -1 a 1 |

### Consultas y respuestas

| Herramienta | Qué devuelve |
| - | - |
| `get_prompts` | Consultas en seguimiento de un sitio, con volumen, estado y geografía |
| `get_prompt_tags` | Etiquetas de consultas del sitio, con recuentos por etiqueta |
| `get_personas` | Perfiles de audiencia configurados en el sitio, con recuentos de consultas por perfil |
| `get_topics` | Temas activos del sitio, con recuento de consultas activas por tema |
| `get_responses` | Respuestas de IA del sitio, con fuentes citadas, sentimiento y posición. Usa `include_response: false` y `compact_sources: true` para una exportación ligera a nivel de variación |
| `get_response_detail` | Una respuesta de IA con fuentes, menciones y detalles de posición completos |
| `get_response_streaming_status` | Estado y progreso de cola de la última ejecución de respuestas o de una concreta |

### Contenido

| Herramienta | Qué devuelve |
| - | - |
| `get_tracked_content` | Contenido en seguimiento con métricas de citas, menciones e impresiones |
| `list_content` | Todos los elementos de contenido, publicados o no, con los ID de sus consultas objetivo |
| `get_content_detail` | Texto completo de un elemento: plan, cuerpo, URL citadas, enlaces, estado y consultas para las que se ha escrito |
| `get_content_citation_prompts` | Consultas cuyas respuestas de IA han citado un elemento de contenido |
| `get_content_hub_sheets` | Pestañas del centro de contenido configuradas en un sitio |
| `get_content_status` | Estado de generación normalizado (running / succeeded / failed) de un elemento |
| `get_content_draft` | Texto del borrador actual: cuerpo del artículo, plan, estado y última versión |
| `get_content_versions` | Historial de versiones, de más reciente a más antigua, con etiquetas y autores |
| `get_content_version` | Texto completo de una versión guardada |

Dos de ellas responden preguntas distintas sobre la misma página y conviene
distinguirlas. `get_content_detail` y `list_content` devuelven las consultas
**para las que se ha escrito** (sus objetivos, los mismos ID que recibe
`create_content`); procede del registro de contenido y no depende de que haya
aparecido ninguna respuesta de IA. `get_content_citation_prompts` devuelve
consultas cuyas respuestas **han citado** la página en un intervalo, por lo que
puede estar legítimamente vacío si aún no se ha citado.

Los objetivos incluyen consultas eliminadas después, marcadas con `status: "deleted"`,
porque la página se escribió para ellas y el centro de contenido sigue mostrándolas.
`get_prompts` no lista consultas eliminadas, por lo que un ID de objetivos puede
no resolverse allí; por eso `get_content_detail` devuelve el texto en línea.
Los objetivos se limitan a 100 entradas por página (25 ID por fila en `list_content`),
con el tamaño sin truncar en `prompts_total` / `prompt_count`.

### Base de conocimientos

Requiere que la base de conocimientos esté activada para la organización; si no,
estas herramientas devuelven un error que lo explica.

| Herramienta | Qué devuelve |
| - | - |
| `search_brand_facts` | Búsqueda semántica de hechos de marca aprobados, incluidos los no clasificados en ningún pilar |
| `get_brand_facts` | Listado paginado de hechos con filtros de pilar, estado de revisión, tipo de fuente y sin clasificar |
| `get_pillars` | Pilares con recuentos de hechos aprobados y disponibilidad de documento sintetizado |
| `get_pillar_document` | Documento Markdown sintetizado de un pilar |

### Fuentes y competidores

| Herramienta | Qué devuelve |
| - | - |
| `get_sources` | Principales dominios raíz citados, clasificados como propios / competidores / socios / terceros |
| `get_source_pages` | URL individuales citadas con métricas por URL |
| `get_competitors` | Competidores en seguimiento de un sitio |
| `get_identifiers` | Nombres, alias y dominios que cuentan como menciones de tu marca o un competidor |

### Contacto

| Herramienta | Qué hace | Permiso con sesión iniciada |
| - | - | - |
| `list_outreach_contacts` | Contactos guardados de Contacto, con autor, correo y su fuente y borrador | Contenido: lectura |
| `find_outreach_author` | Encuentra y guarda autor y correo de una página citada, o página de contacto del sitio | Contenido: escritura |
| `draft_outreach_message` | Redacta y guarda una propuesta con las instrucciones del equipo | Contenido: escritura |
| `update_outreach_contact` | Edita autor, correo, LinkedIn o borrador de un contacto | Contenido: escritura |
| `set_outreach_status` | Mueve páginas entre estados del flujo de Contacto | Contenido: escritura |

### Propuestas

| Herramienta | Qué devuelve |
| - | - |
| `list_pitches` | Informes de propuestas de la organización |
| `get_pitch` | Un informe: competidores, consultas, atributos, principales fuentes citadas y métricas |

### Cuenta y configuración

| Herramienta | Qué devuelve |
| - | - |
| `list_websites` | Sitios a los que acceden tus credenciales, con el país objetivo de cada uno (`baseCountry`) |
| `get_groups` | Grupos de la organización (clave global o sesión de administrador de organización) |
| `get_group_detail` | Un grupo con sus sitios miembros (clave global o sesión de administrador de organización) |
| `get_user_by_email` | Búsqueda por correo, limitada a la organización del solicitante (clave global o sesión de administrador de organización) |
| `get_date_range` | Fechas de respuesta más antigua y reciente del sitio |
| `get_locations` | Geografías configuradas en el sitio |
| `get_saved_views` | Configuraciones de filtros guardadas del sitio |
| `get_group_saved_views` | Vistas guardadas compartidas en un grupo |
| `get_credits_website` | Saldo de créditos del sitio |
| `get_credits_organization` | Saldo de créditos de la organización |
| `get_credit_usage` | Totales de uso, intervalos temporales y desglose paginado por reserva a la que se han cargado créditos |
| `get_credit_usage_events` | Cargos y reembolsos paginados, acciones registradas y atribución al sitio de origen |

Las herramientas de uso de créditos aceptan `website_id` para identificar la
organización, `range` opcional (`24h`, `7d`, `30d`, `90d` o `all`) y `window`
opcional en UTC con `start_at_utc` y `end_at_utc`. Usa un intervalo explícito
para meses naturales. Para páginas siguientes, conserva el intervalo devuelto
y usa `next_offset`; el tamaño predeterminado es 25 y el máximo, 50.
`get_credit_usage_events` también acepta `originating_website_id` de la misma organización.

Los totales describen todo el intervalo solicitado; las páginas de entidades
y eventos pueden ser parciales. Las reservas de grupo a las que se cargan créditos
son distintas de los sitios de origen, los créditos negativos son reembolsos y
«Sin registrar» indica que no hay atribución histórica disponible. Son herramientas
MCP de solo lectura; no añaden endpoints REST públicos.

### Descubrimiento de consultas

| Herramienta | Qué hace | Permiso con sesión iniciada |
| - | - | - |
| `start_prompt_discovery` | Inicia un estudio asíncrono de Descubrir sobre oportunidades de consultas sin seguimiento | Consultas: escritura |
| `find_more_prompt_discovery` | Inicia la siguiente ronda de un estudio terminado para encontrar más consultas | Consultas: escritura |
| `get_prompt_discovery_runs` | Lee el historial visible o el progreso de una ejecución | Consultas: lectura |

Para iniciar un estudio, proporciona `website_id`, `name` y al menos una fuente:
`website_analysis`, `social`, `search_console`, `keyword_gaps`, `competitive_landscape`
o `brand_guidelines`. Puedes especificar `country`, `language`, `prompt_count_range`
con `min` y `max` y `custom_instructions`. La configuración regional predeterminada
es `en-US`, el país Estados Unidos y el objetivo, entre 25 y 50 consultas. Las
franjas actuales son 25 a 50, 50 a 75, 75 a 100, 100 a 150 y 150 a 200.
Seleccionar `brand_guidelines` requiere instrucciones no vacías. Oportunidades
de palabras clave y Panorama competitivo conservan sus restricciones de plan.
Panorama competitivo requiere además un competidor en seguimiento, y Search
Console una integración conectada que aporte información de apoyo.

Revisa fuentes, configuración regional, cantidad e instrucciones antes de lanzar.
Se utilizan servicios externos de investigación y modelos de IA. Tu cliente MCP
gestiona la confirmación; la tarjeta de aprobación del chat de Athena no aparece
por MCP. La cantidad es un objetivo, no una garantía, y el descubrimiento no
añade automáticamente consultas al seguimiento.

Al iniciar se devuelven `run_id` y `version`. Pasa ese ID como `run_id` a
`get_prompt_discovery_runs` para consultar el mismo estudio; no inicies otro
para comprobar el progreso. Sin `run_id`, devuelve historial reciente. `limit`
es 10 por defecto y 20 como máximo. El estado es `pending`, `running`, `completed`,
`partial`, `failed` o `cancelled`; los resultados incluyen `progress_percentage`,
la `phase` actual cuando existe y `total_prompts`. Una ejecución terminada también
incluye `reason_code`, motivo terminal de una completada o código de error de una
fallida, y `reason`, una frase apta para mostrar al usuario que explica una
ejecución fallida, vacía o corta, igual que la línea de Descubrir. Ambos son
`null` si no hay nada que explicar. `rounds` cuenta las rondas de un estudio
continuado con `find_more_prompt_discovery` (1 si nunca se continuó); estado,
progreso y motivo describen la última ronda, y `total_prompts` suma todas.
`can_find_more` indica si puede iniciarse otra ahora y `find_more_reason` explica
por qué no cuando no se puede. Revisa las candidatas en Descubrir de la aplicación.
Estas herramientas no envían notificaciones ni añaden endpoints REST públicos.

Para encontrar más consultas de un estudio terminado, pasa su `run_id` (o el `run_id` de
cualquier ronda terminada que lo continúe) a `find_more_prompt_discovery` junto
con `website_id`. La ronda repite fuentes, país, idioma, objetivo e instrucciones,
omite todas las preguntas sugeridas antes y lee información que no se utilizó.
Cada ronda hace la misma investigación que un estudio nuevo: confirma antes con
el usuario. Un estudio admite una ronda a la vez y como máximo dos después de la
primera, y termina antes si una ronda encuentra menos de diez consultas nuevas
o nada nuevo que leer; en ese caso devuelve un error con el motivo. La respuesta
es el `run_id` y `version` nuevos; consulta su estado con `get_prompt_discovery_runs`
igual que en un estudio nuevo.

### Diagnóstico del sitio

| Herramienta | Qué devuelve |
| - | - |
| `check_ai_access` | Políticas de Robots.txt y respuestas observadas con agentes de usuario de rastreadores desde la red de Athena. Usa `result.evidence` para resultados por agente que pueden ser nulos y separa búsqueda/entrenamiento; comprobaciones fallidas o desafiadas indican acceso desconocido. No garantiza acceso real, indexación ni citas. Incluye un registro de diagnóstico para incidencias con alojamiento o CDN. Solo conexiones con clave de API. |

### Herramientas de escritura

Disponibles con clave de API y en conexiones con sesión vinculadas a una organización.
Con sesión, cada herramienta sigue los permisos de tu rol para su categoría
(columna derecha); las claves actúan con privilegios de administrador en su ámbito.
Todas las escrituras se validan y auditan igual que en el panel.

Para crear una etiqueta de consulta, llama a `create_prompt_tag` con `website_id`
y `tag`. El resultado incluye `tag_id`. Se recortan los espacios de los nombres
y una coincidencia existente sin distinguir mayúsculas devuelve `created: false`.

Antes de cambiar asignaciones, llama a `get_prompts` con el mismo `website_id`
y encuentra la consulta por `id`. Su matriz `tags` contiene asignaciones como
entradas `{ id, name }`. Construye la lista completa de `tag_ids` deseados con
esos ID: añade el nuevo `tag_id` para asignarlo o quita el ID para desasignarlo,
conservando todos los demás. Llama a `set_prompt_tags` con `website_id`, el
`prompt_id` de esa consulta y los `tag_ids` resultantes. Pasa una lista vacía
solo si quieres borrar todas las etiquetas. Repite esta lectura y actualización
para cada consulta.

Los identificadores son nombres, alias y dominios que Athena busca en respuestas
para contar menciones. Antes de cambiarlos, llama a `get_identifiers` con
`website_id` y, para un competidor, su `competitor_id` de `get_competitors`
(omítelo para tu marca). `default_identifiers`, nombre y dominio, siempre se
comparan y no se pueden quitar. Llama después a `update_identifiers` con los
mismos ID y listas `add` y `remove`. Se aplican las reglas de Competidores: se
rechaza un valor ya listado o que utilice otra marca o competidor en seguimiento
del sitio y no se guarda nada. Las respuestas nuevas usan el cambio de inmediato.
Las anteriores solo se reanalizan al ejecutar el reanálisis histórico en
Competidores, con coste de créditos; `changes_awaiting_backfill` cuenta las
ediciones pendientes.

Para seguir competidores nuevos, llama a `add_competitors` con `website_id` y
entre 1 y 25 `competitors`, cada uno con `name` y su `url`, o `no_website: true`
para marcas sin sitio, además de `identifiers` y `additional_urls` opcionales.
Cada uno recibe un resultado: `added` con `competitor_id`, `already_tracked`
si ya se sigue esa URL (sin cambios) o `rejected` con `reason`, como una URL
de tus propios dominios o el límite de 500 competidores por sitio. Para dejar
de seguirlos, llama a `remove_competitors` con hasta 25 `competitor_ids` de
`get_competitors`; cada resultado es `removed`, `no_change` (ya eliminado) o
`not_found`. Se conservan menciones y citas pasadas y Competidores puede
restaurarlos. Ninguna reanaliza respuestas pasadas ni consume créditos: el
reanálisis histórico sigue en Competidores.

| Herramienta | Qué hace | Permiso con sesión iniciada |
| - | - | - |
| `create_prompts` | Crea una o más consultas con temas, etiquetas, perfiles de audiencia y geografía | Consultas: escritura |
| `update_prompt` | Actualiza texto, tipo, tema o geografía de una consulta | Consultas: escritura |
| `create_prompt_tag` | Crea una etiqueta o devuelve una existente con el mismo nombre sin distinguir mayúsculas | Consultas: escritura |
| `set_prompt_tags` | Sustituye las asignaciones de etiquetas de una consulta o las borra con una lista vacía | Consultas: escritura |
| `set_prompts_status` | Pausa o reanuda varias consultas en una llamada | Consultas: escritura |
| `delete_prompt` | Elimina una consulta (de forma lógica si tiene respuestas; física en otro caso) | Consultas: escritura |
| `create_topic` | Crea un tema (devuelve el existente si el nombre está ocupado) | Consultas: escritura |
| `update_topic` | Actualiza nombre o descripción de un tema | Consultas: escritura |
| `delete_topic` | Elimina un tema y, opcionalmente, sus consultas | Consultas: escritura |
| `create_location` | Crea una ubicación geográfica, asociada opcionalmente a consultas | Consultas: escritura |
| `update_location` | Actualiza una ubicación | Consultas: escritura |
| `delete_location` | Elimina una ubicación | Consultas: escritura |
| `update_identifiers` | Añade o quita identificadores de tu marca o competidor (sin reanálisis histórico ni créditos) | Competidores: escritura |
| `add_competitors` | Sigue hasta 25 competidores nuevos con resultado por cada uno (sin reanálisis histórico ni créditos) | Competidores: escritura |
| `remove_competitors` | Deja de seguir hasta 25 competidores, con resultado por cada uno (sin reanálisis histórico ni créditos) | Competidores: escritura |
| `start_response_streaming` | Inicia una ejecución de respuestas para todas las consultas o una selección | Consultas: escritura |
| `start_prompt_discovery` | Inicia un estudio de Descubrir con fuentes, configuración regional e instrucciones opcionales | Consultas: escritura |
| `find_more_prompt_discovery` | Inicia otra ronda de un estudio terminado, omitiendo las sugerencias anteriores | Consultas: escritura |
| `create_content` | Inicia el flujo de contenido (plan o artículo completo a partir de consulta o tema) | Contenido: escritura |
| `add_content` | Añade un artículo ya escrito como borrador editable, versión 1 (sin generación ni créditos) | Contenido: escritura |
| `revise_brief` | Reescribe un plan de contenido a partir de una instrucción y lo registra como versión | Contenido: escritura |
| `approve_brief` | Aprueba un plan e inicia su artículo (consume créditos de contenido) | Contenido: escritura |
| `revise_content` | Reescribe un borrador a partir de una instrucción y lo registra como versión | Contenido: escritura |
| `edit_content` | Aplica cambios exactos de buscar y reemplazar (deterministas, sin IA) y los registra como versión | Contenido: escritura |
| `restore_content_version` | Recupera texto de una versión anterior como borrador actual (añade; nunca elimina) | Contenido: escritura |
| `publish_content` | Marca contenido como publicado en su URL para iniciar el seguimiento de citas | Contenido: escritura |
| `track_content_urls` | Registra URL existentes o de terceros como páginas en seguimiento (en bloque, idempotente, sin créditos) | Contenido: escritura |
| `rename_content` | Cambia el nombre de una fila de contenido | Contenido: escritura |
| `move_content` | Mueve elementos entre hojas (los valores de columnas personalizadas en conflicto se pierden permanentemente) | Contenido: escritura |
| `delete_content` | Elimina una fila de contenido (permanente, sin deshacer) | Contenido: escritura |
| `add_brand_facts` | Añade de 1 a 50 hechos de marca por el flujo completo, con informe de resultado por hecho | Conocimiento de marca: escritura |
| `update_brand_fact` | Actualiza texto, URL de fuente o confianza de un hecho | Conocimiento de marca: escritura |
| `delete_brand_facts` | Elimina permanentemente de 1 a 50 hechos (sin deshacer; informa de ID ausentes sin tratarlos como errores) | Rol de administrador |
| `create_pillar` | Crea un pilar de la base de conocimientos (obtiene o crea por nombre) | Conocimiento de marca: escritura |
| `update_pillar` | Cambia nombre o descripción de un pilar o lo publica o archiva | Conocimiento de marca: escritura |
| `delete_pillars` | Elimina permanentemente de 1 a 20 pilares y todos sus hechos (sin deshacer) | Rol de administrador |
| `merge_pillars` | Fusiona pilares de origen en uno publicado de destino y elimina los de origen | Conocimiento de marca: escritura |
| `move_brand_facts` | Clasifica de 1 a 50 hechos en un pilar publicado (admite hechos sin clasificar) | Conocimiento de marca: escritura |
| `create_saved_view` | Guarda filtros del panel (nombre, icono opcional y objeto `filters` de hasta 64KB guardado literalmente) | Cualquier miembro |

`create_saved_view` es la única escritura abierta a todos los miembros del sitio,
ya que las vistas son configuraciones personales: las creaciones con sesión
se atribuyen al usuario conectado, mientras que las de clave no tienen propietario,
aparecen como creadas por API en el panel y solo los administradores del sitio
pueden editarlas o eliminarlas allí. `create_saved_view`, `move_content` y
`add_content` son las tres herramientas de escritura sin equivalente REST.

`delete_brand_facts` y `delete_pillars` son las dos escrituras limitadas por tu
rol en sí en vez de por un permiso de categoría: eliminar conocimiento de marca
coincide con la eliminación exclusiva de administradores del panel, y eliminar
un pilar borra permanentemente todos sus hechos. Un Editor con escritura de
conocimiento de marca puede actualizar hechos, organizar pilares y fusionarlos,
pero no eliminarlos. Las conexiones con clave cumplen el requisito por su ámbito administrativo.

## Ejemplos de consultas

Una vez conectado, prueba:

* «¿Cuál es mi cuota de voz en respuestas de IA frente a los competidores que sigo este trimestre?»
* «¿Qué dominios se citan más para las consultas que sigo?»
* «Muéstrame la tendencia de mi porcentaje de citas de los últimos 90 días».
* «¿Cuál es mi valor captado de búsquedas con IA y margen de mejora por tema?»
* «Obtén las respuestas de IA que mencionan mi marca y resume su sentimiento».


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.