Scoping por proyecto

El servidor MCP de Almirant soporta un parametro opcional projectId en la URL de conexion que limita automaticamente las operaciones al proyecto indicado. Esto es especialmente util cuando un agente de IA trabaja dentro del contexto de un unico proyecto.

Como funciona

Cuando se configura projectId en la URL de conexion:

• list_projects devuelve unicamente el proyecto configurado
• list_work_items filtra automaticamente por el proyecto
• create_work_item usa el proyecto como valor por defecto
• create_task, create_story, create_feature, create_epic requieren que el projectId este configurado en la sesion
• list_idea_items filtra automaticamente por el proyecto
• list_milestones filtra automaticamente por el proyecto
• get_board_context devuelve boards del proyecto configurado

Sin projectId, los tools operan sobre todos los proyectos de la organizacion.

Configuracion

Anade el parametro projectId como query string en la URL:

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

Como obtener el Project ID

Hay dos formas de encontrar tu Project ID:

Desde la interfaz de Almirant

1. Navega al proyecto deseado en Almirant
2. El UUID aparece en la URL del navegador: https://app.almirant.ai/projects/<project-uuid>/...

Desde MCP sin scoping

Ejecuta el tool list_projects sin projectId configurado para obtener la lista completa de proyectos con sus IDs:

{
  "tool": "list_projects"
}

La respuesta incluira el id de cada proyecto:

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Mi Proyecto"
    }
  ]
}

Override por parametro

Los tools que aceptan un parametro projectId explicito siempre tienen prioridad sobre el valor configurado en la sesion. Esto permite realizar operaciones puntuales sobre otro proyecto sin cambiar la configuracion:

{
  "tool": "list_work_items",
  "params": {
    "projectId": "otro-project-uuid"
  }
}

Tools afectados por el scoping

Tool	Comportamiento con projectId
list_projects	Devuelve solo el proyecto configurado
list_work_items	Filtra por proyecto automaticamente
create_work_item	Usa el proyecto como defecto si no se pasa projectId
create_task	Requiere projectId en sesion (no acepta parametro)
create_story	Requiere projectId en sesion (no acepta parametro)
create_feature	Requiere projectId en sesion (no acepta parametro)
create_epic	Requiere projectId en sesion (no acepta parametro)
get_board_context	Devuelve boards del proyecto configurado
get_project_roadmap	Usa el proyecto configurado como fallback
list_idea_items	Filtra por proyecto automaticamente
list_milestones	Usa el proyecto configurado como fallback
create_milestone	Usa el proyecto configurado como fallback
get_implement_context	Usa el proyecto configurado como fallback
get_ideation_context	Usa el proyecto configurado como fallback
get_validate_context	Usa el proyecto configurado como fallback
resolve_work_items	Filtra resultados por proyecto si esta configurado

Recomendacion

Para flujos de trabajo con agentes de IA, se recomienda siempre configurar el projectId en la URL de conexion. Esto evita errores por falta de contexto y asegura que todas las operaciones se realicen sobre el proyecto correcto.