Connect with Claude Code

This is the core integration of Almirant. By connecting your IDE with Almirant via MCP (Model Context Protocol), the AI can read your tasks, implement code, move work items between columns, and create pull requests -- all without leaving the editor.

What is MCP and why connect

MCP (Model Context Protocol) is an open protocol that allows AI tools (like Claude Code or Cursor) to communicate with external services bidirectionally. When you connect Almirant via MCP:

• The AI reads your work items, boards, and sprints directly
• The AI updates task status as it implements
• The AI creates new work items when it detects subtasks
• The AI accesses the project context (tech stack, description, objectives)

Requirements

Before you begin, make sure you have:

• Claude Code installed -- Installation instructions
• A project created in Almirant -- Create your first project
• An Almirant API Key -- We'll generate one in the next step

Step 1: Generate an API Key

1. In Almirant, go to Settings from the sidebar
2. Navigate to the API Keys section
3. Click Create API Key
4. Give it a descriptive name (for example, "Claude Code - Work laptop")
5. Copy the generated API Key

Save your API Key

The API Key is only shown once when created. Copy it and store it in a safe place. If you lose it, you'll need to generate a new one.

Step 2: Get the Project ID

You need the ID of the project you want to connect the AI to. There are two ways to get it:

Option A: From the URL

Open your project in Almirant and copy the UUID that appears in the browser URL:

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                              └──────────── this is your projectId ────────────┘

Option B: From the MCP tool

If you set up the connection without a projectId, you can use the list_projects tool to see all your projects and their IDs.

Step 3: Configure .mcp.json

Create or edit the .mcp.json file at the root of your repository:

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

Replace the values:

Placeholder	Value
<your-project-id>	The project UUID obtained in Step 2
<your-api-key>	The API Key generated in Step 1

Example with real values:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}

.mcp.json file in the repository

You can include the .mcp.json in your repository so the entire team shares the same configuration. If you do, add the API Key as an environment variable instead of including it directly in the file.

Step 4: Verify the connection

Open Claude Code in your terminal and verify that the connection works:

1. Start Claude Code in the directory of the project where you created .mcp.json
2. Ask Claude to list your projects:

> List my Almirant projects

If the connection is correct, Claude will respond with the project listing. If you have projectId configured, it will show the details of the specific project.

MCP tools available after connection:

Tool	Description
list_projects	Lists available projects
list_boards	Lists the project's boards
list_work_items	Lists work items with filters
create_work_item	Creates a new work item
update_work_item	Updates an existing work item
list_sprints	Lists the project's sprints

Configuration for Cursor

The configuration for Cursor is identical. The difference is in the location of the configuration file:

Cursor uses the same .mcp.json format. Place the file at the root of your project or in Cursor's global configuration according to your version's documentation.

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

Troubleshooting

The connection fails or doesn't respond

1. Check the URL -- Make sure the URL is https://api.almirant.ai/mcp (not https://almirant.ai/mcp)
2. Verify the API Key -- Generate a new one if you're not sure the current one is correct
3. Check the JSON format -- A syntax error in .mcp.json will prevent the connection

"Unauthorized" or "Invalid API Key"

• The API Key may have been revoked or expired
• Go to Settings > API Keys in Almirant and generate a new one
• Update the value in your .mcp.json

"Project not found"

• Verify that the projectId in the URL is correct
• Check that you have access to the project with your account
• Try without projectId and use list_projects to see the available IDs

Claude Code doesn't detect the MCP server

• Make sure the .mcp.json file is at the root of the directory where you run Claude Code
• Restart Claude Code after creating or modifying the file
• Verify that the JSON is valid (no extra commas, correct quotes)

---

Next step: Your first AI flow -- Implement a complete task using AI from your IDE.