Project Scoping

The Almirant MCP server supports an optional projectId parameter in the connection URL that automatically limits operations to the specified project. This is especially useful when an AI agent works within the context of a single project.

How it works

When projectId is configured in the connection URL:

• list_projects returns only the configured project
• list_work_items automatically filters by the project
• create_work_item uses the project as default value
• create_task, create_story, create_feature, create_epic require projectId to be configured in the session
• list_idea_items automatically filters by the project
• list_milestones automatically filters by the project
• get_board_context returns boards from the configured project

Without projectId, tools operate across all projects in the organization.

Configuration

Add the projectId parameter as a query string in the URL:

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

How to get the Project ID

There are two ways to find your Project ID:

From the Almirant interface

1. Navigate to the desired project in Almirant
2. The UUID appears in the browser URL: https://app.almirant.ai/projects/<project-uuid>/...

From MCP without scoping

Run the list_projects tool without projectId configured to get the full list of projects with their IDs:

{
  "tool": "list_projects"
}

The response will include the id of each project:

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

Parameter override

Tools that accept an explicit projectId parameter always take priority over the value configured in the session. This allows you to perform one-off operations on another project without changing the configuration:

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

Tools affected by scoping

Tool	Behavior with projectId
list_projects	Returns only the configured project
list_work_items	Automatically filters by project
create_work_item	Uses the project as default if projectId is not passed
create_task	Requires projectId in session (does not accept parameter)
create_story	Requires projectId in session (does not accept parameter)
create_feature	Requires projectId in session (does not accept parameter)
create_epic	Requires projectId in session (does not accept parameter)
get_board_context	Returns boards from the configured project
get_project_roadmap	Uses the configured project as fallback
list_idea_items	Automatically filters by project
list_milestones	Uses the configured project as fallback
create_milestone	Uses the configured project as fallback
get_implement_context	Uses the configured project as fallback
get_ideation_context	Uses the configured project as fallback
get_validate_context	Uses the configured project as fallback
resolve_work_items	Filters results by project if configured

Recommendation

For AI agent workflows, it is recommended to always configure the projectId in the connection URL. This avoids errors due to missing context and ensures that all operations are performed on the correct project.