Escopo por projeto

O servidor MCP do Almirant oferece suporte a um parâmetro opcional projectId na URL de conexão que limita automaticamente as operações ao projeto indicado. Isso é especialmente útil quando um agente de IA trabalha no contexto de um único projeto.

Como funciona

Quando projectId é configurado na URL de conexão:

• list_projects retorna apenas o projeto configurado
• list_work_items filtra automaticamente pelo projeto
• create_work_item usa o projeto como valor padrão
• create_task, create_story, create_feature, create_epic exigem que projectId esteja configurado na sessão
• list_idea_items filtra automaticamente pelo projeto
• list_milestones filtra automaticamente pelo projeto
• get_board_context retorna os boards do projeto configurado

Sem projectId, as ferramentas operam em todos os projetos da organização.

Configuração

Adicione o parâmetro projectId como query string à URL:

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

Como obter o ID do projeto

Há duas formas de encontrar o ID do projeto:

Pela interface do Almirant

1. Navegue até o projeto desejado no Almirant
2. O UUID aparece na URL do navegador: https://app.almirant.ai/projects/<project-uuid>/...

Pelo MCP sem escopo

Execute a ferramenta list_projects sem projectId configurado para obter a lista completa de projetos com seus IDs:

{
  "tool": "list_projects"
}

A resposta inclui o id de cada projeto:

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

Substituição por parâmetro

As ferramentas que aceitam um parâmetro projectId explícito sempre têm prioridade sobre o valor configurado na sessão. Isso permite realizar operações pontuais em outro projeto sem alterar a configuração:

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

Ferramentas afetadas pelo escopo

Ferramenta	Comportamento com projectId
list_projects	Retorna apenas o projeto configurado
list_work_items	Filtra automaticamente pelo projeto
create_work_item	Usa o projeto como padrão se projectId não for informado
create_task	Exige projectId na sessão (não aceita parâmetro)
create_story	Exige projectId na sessão (não aceita parâmetro)
create_feature	Exige projectId na sessão (não aceita parâmetro)
create_epic	Exige projectId na sessão (não aceita parâmetro)
get_board_context	Retorna os boards do projeto configurado
get_project_roadmap	Usa o projeto configurado como fallback
list_idea_items	Filtra automaticamente pelo projeto
list_milestones	Usa o projeto configurado como fallback
create_milestone	Usa o projeto configurado como fallback
get_implement_context	Usa o projeto configurado como fallback
get_ideation_context	Usa o projeto configurado como fallback
get_validate_context	Usa o projeto configurado como fallback
resolve_work_items	Filtra os resultados pelo projeto se ele estiver configurado

Recomendação

Para fluxos de trabalho com agentes de IA, recomendamos sempre configurar projectId na URL de conexão. Isso evita erros por falta de contexto e garante que todas as operações sejam realizadas no projeto correto.