MCP Authentication

The Almirant MCP server requires a valid API Key for all operations. Authentication is done via the Authorization header with a Bearer token.

Obtaining an API Key

1. In Almirant, go to Settings from the sidebar menu
2. Navigate to the API Keys section
3. Click Create API Key
4. Give it a descriptive name (for example, "Claude Code - My Project")
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 will need to generate a new one.

For more details on API Key management, see the API Keys documentation in the features section.

MCP server URL

https://api.almirant.ai/mcp

For local development:

http://localhost:3001/mcp

Authentication header

All requests must include the header:

Authorization: Bearer <your-api-key>

Configuration in Claude Code

Create or edit the .mcp.json file in the root of your project:

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

Project scoping

To limit operations to a specific project, add the projectId parameter to the URL. See Project Scoping for more details.

Configuration in Cursor

Cursor supports MCP natively. Add the configuration to Cursor's MCP settings file (.cursor/mcp.json):

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

Global configuration (all projects)

If you prefer Almirant to be available in all your projects without creating a .mcp.json in each one, add the configuration to ~/.claude/settings.json:

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

Common authentication errors

Code	Message	Cause	Solution
401	Unauthorized	API Key missing or invalid	Verify that the Authorization header includes Bearer <api-key>
401	API key expired	The API Key has been revoked	Generate a new API Key in Settings
403	Forbidden	The API Key does not have permissions for the requested resource	Verify the API Key permissions
500	Error: could not resolve organizationId from API key	The API Key is not associated with an organization	Generate a new API Key from the correct organization

Verifying the connection

Once configured, you can verify that the connection works using the get_current_user tool:

{
  "tool": "get_current_user"
}

This tool returns the authenticated user's profile, including id, name, email, and organizationId. If authentication fails, you will receive a descriptive error.