MCP-Authentifizierung

Der MCP-Server von Almirant erfordert für alle Vorgänge einen gültigen API Key. Die Authentifizierung erfolgt über den Header Authorization mit einem Bearer-Token.

API Key erhalten

1. Rufe in Almirant Settings über das Seitenmenü auf
2. Navigiere zum Bereich API Keys
3. Klicke auf API Key erstellen
4. Gib ihm einen aussagekräftigen Namen (zum Beispiel „Claude Code - Mein Projekt“)
5. Kopiere den generierten API Key

API Key aufbewahren

Der API Key wird beim Erstellen nur einmal angezeigt. Kopiere ihn und bewahre ihn an einem sicheren Ort auf. Wenn du ihn verlierst, musst du einen neuen erstellen.

Weitere Informationen zur Verwaltung von API Keys findest du in der API-Key-Dokumentation im Funktionsbereich.

URL des MCP-Servers

https://api.almirant.ai/mcp

Für die lokale Entwicklung:

http://localhost:3001/mcp

Authentifizierungs-Header

Alle Anfragen müssen den folgenden Header enthalten:

Authorization: Bearer <tu-api-key>

Konfiguration in Claude Code

Erstelle oder bearbeite die Datei .mcp.json im Stammverzeichnis deines Projekts:

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

Projektbezogene Eingrenzung

Um Vorgänge auf ein bestimmtes Projekt zu beschränken, füge den Parameter projectId zur URL hinzu. Weitere Informationen findest du unter Projektbezogene Eingrenzung.

Konfiguration in Cursor

Cursor unterstützt MCP nativ. Füge die Konfiguration in der MCP-Einstellungsdatei von Cursor (.cursor/mcp.json) hinzu:

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

Globale Konfiguration (alle Projekte)

Wenn du möchtest, dass Almirant in allen deinen Projekten verfügbar ist, ohne in jedem Projekt eine .mcp.json zu erstellen, füge die Konfiguration in ~/.claude/settings.json hinzu:

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

Häufige Authentifizierungsfehler

Code	Meldung	Ursache	Lösung
401	Unauthorized	API Key fehlt oder ist ungültig	Prüfe, ob der Header Authorization Bearer <api-key> enthält
401	API key expired	Der API Key wurde widerrufen	Erstelle in Settings einen neuen API Key
403	Forbidden	Der API Key hat keine Berechtigung für die angeforderte Ressource	Prüfe die Berechtigungen des API Keys
500	Error: could not resolve organizationId from API key	Der API Key ist keiner Organisation zugeordnet	Erstelle einen neuen API Key in der richtigen Organisation

Verbindung überprüfen

Nach der Konfiguration kannst du mit dem Tool get_current_user überprüfen, ob die Verbindung funktioniert:

{
  "tool": "get_current_user"
}

Dieses Tool gibt das Profil des authentifizierten Benutzers zurück, einschließlich id, name, email und organizationId. Wenn die Authentifizierung fehlschlägt, erhältst du einen aussagekräftigen Fehler.