Autenticacion MCP

El servidor MCP de Almirant requiere una API Key valida para todas las operaciones. La autenticacion se realiza mediante el header Authorization con un token Bearer.

Obtener una API Key

1. En Almirant, accede a Settings desde el menu lateral
2. Navega a la seccion API Keys
3. Haz clic en Crear API Key
4. Dale un nombre descriptivo (por ejemplo, "Claude Code - Mi Proyecto")
5. Copia la API Key generada

Guarda tu API Key

La API Key solo se muestra una vez al crearla. Copiala y guardala en un lugar seguro. Si la pierdes, tendras que generar una nueva.

Para mas detalles sobre la gestion de API Keys, consulta la documentacion de API Keys en la seccion de funcionalidades.

URL del servidor MCP

https://api.almirant.ai/mcp

Para desarrollo local:

http://localhost:3001/mcp

Header de autenticacion

Todas las peticiones deben incluir el header:

Authorization: Bearer <tu-api-key>

Configuracion en Claude Code

Crea o edita el archivo .mcp.json en la raiz de tu proyecto:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Scoping por proyecto

Para limitar las operaciones a un proyecto concreto, anade el parametro projectId a la URL. Consulta Scoping por proyecto para mas detalles.

Configuracion en Cursor

Cursor soporta MCP de forma nativa. Anade la configuracion en el archivo de settings de MCP de Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Configuracion global (todos los proyectos)

Si prefieres que Almirant este disponible en todos tus proyectos sin crear un .mcp.json en cada uno, anade la configuracion en ~/.claude/settings.json:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Errores comunes de autenticacion

Codigo	Mensaje	Causa	Solucion
401	Unauthorized	API Key ausente o invalida	Verifica que el header Authorization incluye Bearer <api-key>
401	API key expired	La API Key ha sido revocada	Genera una nueva API Key en Settings
403	Forbidden	La API Key no tiene permisos para el recurso solicitado	Verifica los permisos de la API Key
500	Error: could not resolve organizationId from API key	La API Key no esta asociada a una organizacion	Genera una nueva API Key desde la organizacion correcta

Verificar la conexion

Una vez configurado, puedes verificar que la conexion funciona usando el tool get_current_user:

{
  "tool": "get_current_user"
}

Este tool devuelve el perfil del usuario autenticado, incluyendo id, name, email y organizationId. Si la autenticacion falla, recibiras un error descriptivo.