🔧 Instalar y autenticar

¿Eres nuevo aquí? Una clave de API (API key, sigla de application programming interface — «interfaz de programación de aplicaciones»: la puerta por la que se comunican dos programas. Es un código único, generalmente una secuencia larga de letras y números, que el servicio usa para saber quién hace el pedido y cobrar (o limitar) el uso correctamente. Piensa en ella como una credencial de visitante: sin ella, la recepción (el servidor del servicio) ni siquiera te deja entrar. Obtienes esta clave al crear una cuenta en el sitio del servicio. En Firecrawl, por ejemplo, hay un botón «Get API key» en el panel, después de un registro rápido, generalmente con un plan gratuito que ya te permite hacer pruebas.

Cada servidor MCP (el “conector” que le da manos a tu agente, explicado en los módulos anteriores) se comunica con un servicio externo diferente, y cada servicio tiene su propia clave. Firecrawl (que extrae datos de páginas web) tiene una clave; si después conectas un servidor MCP de correo electrónico o de hojas de cálculo, cada uno te pedirá la suya. Ninguna de estas claves se mezcla: cada una abre solo la puerta de su servicio.

¿Eres nuevo aquí? Un archivo .env es un archivo de texto simple, dentro de la carpeta de tu proyecto, que guarda secretos —claves, contraseñas— fuera del código y de la conversación. Nunca debe compartirse ni subirse al GitHub (el sitio donde se guarda y versiona el código de tu proyecto — la Trilha 0 ya explicó cómo organizar tu carpeta; el .env va junto, pero recibe un tratamiento especial).

El nombre del archivo empieza con un punto a propósito: en sistemas tipo Unix (Mac y Linux), los archivos que empiezan con un punto quedan «ocultos» por defecto — no aparecen en una lista común de archivos, lo que reduce la posibilidad de que los arrastres sin querer a algún lugar público. Aun así, la protección de verdad no es el nombre, sino el .gitignore — un segundo archivo de texto que le dice a git "nunca sigas estos archivos".

Objetivo: guardar la clave fuera del alcance del chat y del control de versiones. Cómo verificar: abre el archivo .gitignore del proyecto y confirma que la línea .env está ahí: así git nunca intentará subir este archivo.

Leyenda: la clave se crea en el sitio del servicio, se guarda solo en el archivo .env y el agente la lee de ahí cuando la necesita — el .gitignore y el hábito de nunca escribir la clave en el chat cierran las dos vías de filtración más comunes.

Nunca pegues una clave de API directamente en la conversación con Claude Code. La conversación puede quedar guardada en los registros, alguien puede revisarla después e incluso podría filtrarse en una captura de pantalla compartida por accidente. El archivo .env existe precisamente para aislar ese secreto: el agente lo lee de allí cuando lo necesita, sin que tengas que volver a escribirlo en cada sesión.

Esta regla también se aplica cuando parece más rápido «solo pegarlo aquí para probar». El ahorro de tiempo es de segundos; el riesgo es que la clave quede registrada en un lugar que ya no controlas. Si algún día necesitas mostrar tu historial de conversación a alguien — al soporte técnico, a un colega, en una captura de un error — quieres tener la certeza absoluta de que no haya ningún secreto allí.

Leyenda: los cuatro pasos estándar para conectar cualquier servidor MCP de forma segura: la clave nunca pasa por la conversación, solo por el archivo .env.

Con la clave ya en .env, iniciar el servidor suele requerir un solo comando dentro de Claude Code —el propio agente puede ejecutarlo por ti si le pides «instala y configura el servidor MCP de Firecrawl». Lee la clave de .env automáticamente, sin que tengas que copiarla y pegarla de nuevo.

Objetivo: dejar el servidor MCP listo para usar. Cómo verificar: ejecuta /mcp en Claude Code y comprueba si "firecrawl" aparece en la lista con el estado conectado.

Si el comando de instalación da error, lo más común es que falte alguna dependencia del sistema (el propio agente suele indicar qué falta y cómo instalarlo) o que el nombre de la variable en .env no coincida con el que espera el servidor. Comprueba que hayas escrito exactamente FIRECRAWL_API_KEY, sin espacios antes ni después del signo igual.

Antes de confiarle al servidor un trabajo grande, haz una prueba con una solicitud pequeña y fácil de verificar; por ejemplo, pedir el título de una página conocida. Si el resultado coincide con lo que esperas, el servidor está funcionando bien.

Objetivo: confirmar que la autenticación y la conexión funcionan de principio a fin. Cómo verificar: el agente debe devolver el título real de la página, sin errores de autenticación ni tiempos de espera agotados.

No todos los errores en la prueba tienen que ver con la clave. Algunos son del servicio y otros, del sitio al que intentas acceder. Reconocer cuál es cuál ahorra tiempo y evita que estés modificando el .env cuando el problema está en otro lugar.

Si sospechas que se filtró una clave (por ejemplo, apareció sin querer en una captura de pantalla o en un repositorio público), cámbiala de inmediato: genera una nueva en el panel del servicio, revoca (cancela) la antigua y actualiza solo el archivo .env — nada más cambia en el proyecto.

¿Eres nuevo aquí? Revocar significa cancelar la validez de esa clave específicamente: el servicio empieza a rechazar cualquier solicitud que llegue con ella, aunque la persona que la copió todavía la tenga guardada en algún lugar. Es diferente de "eliminar tu cuenta": sigues teniendo acceso normal al servicio, pero con una clave nueva.

Leyenda: el paso 3 (revocar) es el único que realmente cierra el acceso de la clave filtrada: generar una clave nueva sin revocar la anterior deja ambas válidas al mismo tiempo.