# Claude Code verbinden

> Claude Code und andere MCP-Clients arbeiten in nexxus als die angemeldete Person. Wie eine Administratorin oder ein Administrator das erlaubt, wie jede Person ihren eigenen Client verbindet, was der Client darf, wie Änderungen bestätigt werden und wie man trennt.

nexxus ist ein MCP-Server. Claude Code und andere Clients, die das Model Context Protocol sprechen, verbinden sich damit und arbeiten mit Ihren Daten so wie der KI-Assistent in der Anwendung: einen Kunden nachschlagen, ein Projekt mit seinen Sätzen lesen, die Dokumente eines Vorgangs finden, einen Feiertag anlegen oder einen Datensatz ändern. Der Client meldet sich im Browser als Sie an und hat danach genau Ihre Rechte. Ihr Passwort sieht er nie.

Wer ohnehin den ganzen Tag in Claude Code arbeitet, fragt dort, ohne das Terminal zu verlassen, welche Projekte eines Kunden noch offen sind, und lässt eine Korrektur buchen. Bevor eine Aktion der Anwendung einen Datensatz ändert, zeigt Claude Code die Änderung so, wie nexxus sie beschreibt, und es passiert nichts, bis Sie zustimmen.

## Bevor Sie anfangen

- Eine Administratorin oder ein Administrator erlaubt externe KI-Clients für die Organisation (Schritt 1 unten). Bis dahin wird jeder Client abgewiesen.
- Claude Code ist auf Ihrem Rechner installiert. Andere MCP-Clients gehen auch, wenn sie den Transport Streamable HTTP und die Anmeldung per OAuth beherrschen; siehe [Was der Client können muss](#was-der-client-können-muss).
- Ihr nexxus-Konto. Hat es eine Authenticator-App, halten Sie sie bereit: Die Bestätigung der Verbindung fragt nach einem Code.

## Einen Client verbinden

<Steps>

1. **Administration, einmalig:** Öffnen Sie <MenuPath to="Administration > Betrieb > Systemkonfiguration" />. Schalten Sie im Abschnitt <Ui>Externe KI-Clients (MCP)</Ui> den Schalter <Ui>Externe KI-Clients erlauben</Ui> ein und klicken Sie auf <Ui>Speichern</Ui>. Unter dem Schalter steht als <Ui>Adresse für MCP-Clients</Ui> die Adresse, mit der sich Clients verbinden.

2. Öffnen Sie <MenuPath to="Mein Profil > KI-Clients" />. Kopieren Sie unter <Ui>Befehl für Claude Code</Ui> den Befehl. Er sieht so aus, mit Ihrer Adresse:

   ```bash
   claude mcp add --transport http nexxus https://<Ihre nexxus-Adresse>/api/mcp
   ```

3. Führen Sie den Befehl in einem Terminal aus und starten Sie Claude Code. Es meldet, dass der Server eine Anmeldung braucht. Tippen Sie `/mcp`, wählen Sie `nexxus` und dann <Ui>Authenticate</Ui>. Claude Code öffnet Ihren Browser.

4. Melden Sie sich wie gewohnt auf der Anmeldeseite von nexxus an. Sind Sie in diesem Browser schon bei nexxus angemeldet, entfällt dieser Schritt.

5. nexxus zeigt die Zustimmungsseite. Sie nennt den Client so, wie er sich selbst nennt, Ihr Konto, wohin die Antwort geht (bei Claude Code `localhost` mit einem Port) und was der Client darf. Geben Sie den Code aus Ihrer Authenticator-App ein, oder Ihr Passwort, wenn Ihr Konto keine App hat, und klicken Sie auf <Ui>Verbinden</Ui>.

6. Der Browser gibt an Claude Code zurück, und Claude Code meldet die Verbindung. Fragen Sie etwas, zum Beispiel „Welche Datensatzarten kannst du in nexxus lesen?“.

</Steps>

Bestätigen Sie die Zustimmungsseite nur, wenn Sie die Verbindung gerade selbst gestartet haben.

### Andere Clients

claude.ai und Claude Desktop fügen entfernte MCP-Server als benutzerdefinierte Connectoren mit derselben Adresse hinzu. nexxus nimmt die Rücksprungadresse von claude.ai an (`https://claude.ai/api/mcp/auth_callback` und `https://claude.com/api/mcp/auth_callback`). Geprüft ist diese Seite mit Claude Code; die Oberfläche von claude.ai beschreibt sie nicht.

#### Was der Client können muss

| Voraussetzung | Warum |
|---|---|
| Transport Streamable HTTP (Protokoll `2025-03-26`, `2025-06-18` oder `2025-11-25`) | Einen anderen Transport bietet nexxus externen Clients nicht an |
| OAuth mit PKCE (S256) und dynamischer Registrierung (RFC 7591) | Der Client registriert sich selbst unter `/oauth2/register` und meldet die Person an |
| Eine Rücksprungadresse auf dem eigenen Rechner der Person (`http://localhost:<Port>/...`, `127.0.0.1` oder `[::1]`) oder eine, die der Betrieb erlaubt hat | An andere Adressen schickt nexxus keinen Anmeldecode |
| Elicitation (Rückfragen des Servers an die Person) | Ohne sie lehnt nexxus jede Aktion ab, die Ihre Bestätigung braucht |

## Was der Client darf

Der Client bekommt dieselben Werkzeuge wie Ihr Assistent in der Anwendung, soweit Ihre Organisation sie eingeschaltet hat, und in jedem Werkzeug Ihre Rechte. Werkzeuge, die den Chat der Anwendung brauchen, fehlen, etwa eine Seite in Ihrem Browser öffnen oder eine Datei in einer Unterhaltung erzeugen. Drei kommen hinzu:

| Werkzeug | Was es tut |
|---|---|
| `nx_record_types`, `nx_record_search`, `nx_record_get` | Datensätze aller Bereiche lesen, die Sie in der Anwendung öffnen dürfen, mit den Filtern der Liste und der Rechteprüfung der Detailansicht. Diese hat auch der KI-Assistent in der Anwendung. |
| `nx_action_execute` | Eine Aktion der Anwendung ausführen: anlegen, ändern, löschen oder die eigene Aktion eines Moduls. Nur für externe Clients. |
| `nx_mcp_connections` | Ihre verbundenen Clients und die Adresse zum Verbinden eines neuen |

Die beiden Rechteschlüssel hinter den neuen Werkzeugen, `RECORD_READ` und `ACTION_EXECUTE`, bringt der eingebaute Connector „Aktionen in der App“ mit.

### Aktionen werden vorher bestätigt

Bevor `nx_action_execute` etwas ändert, prüft nexxus die Eingaben wie die Vorschaukarte in der Anwendung. Scheitert eine Prüfung, bekommt der Client den Grund, und es wird nichts gefragt. Bestehen alle Prüfungen, fragt nexxus Sie über den Client. Claude Code zeigt dann einen Dialog, der mit „MCP server "nexxus" requests your input“ beginnt, gefolgt von der Änderung, wie nexxus sie beschreibt, zum Beispiel:

```text
Feiertag ändern
Datensatz: MCP-Testtag
- Name: MCP-Testtag-neu
```

<Ui>Accept</Ui> führt die Änderung aus, <Ui>Decline</Ui> oder <Ui>Esc</Ui> lässt alles, wie es war. Ein Löschen ist nicht vorab angekreuzt. Kommt innerhalb von 10 Minuten keine Antwort, passiert nichts. Ein Client, der nicht nachfragen kann, bekommt eine Ablehnung und ändert nichts. Schreibende Werkzeuge von Connectoren und Modulen fragen genauso.

Auch jedes andere Werkzeug, das etwas ändert, fragt vorher, etwa beim Speichern einer Notiz über Sie, eines Wissenseintrags oder eines Skills. Die Rückfrage nennt dann das Werkzeug und alle Eingaben, und nichts ist vorab angekreuzt. Zusätzlich gelten die eigenen Freigaberegeln von Claude Code für MCP-Werkzeuge.

## Trennen

<MenuPath to="Mein Profil > KI-Clients" /> zeigt jeden verbundenen Client mit <Ui>verbunden seit</Ui>, <Ui>zuletzt benutzt</Ui> und wo er läuft. <Ui>Trennen</Ui> entzieht ihm sofort den Zugriff: Seine nächste Anfrage wird abgewiesen, und Claude Code bittet unter `/mcp` um eine neue Anmeldung. Um den Client wieder zu nutzen, verbinden Sie ihn neu.

Schaltet eine Administratorin oder ein Administrator <Ui>Externe KI-Clients erlauben</Ui> aus, sind alle Verbindungen der Organisation sofort gesperrt. Sie gehen wieder, sobald der Schalter wieder an ist, solange ihre Anmeldung nicht abgelaufen ist.

## Was im Hintergrund passiert

<Sequence
  actors={[
    { name: 'Claude Code', icon: 'terminal' },
    { name: 'Browser', icon: 'monitor' },
    { name: 'nexxus', icon: 'server' },
  ]}
  steps={[
    { from: 0, to: 2, label: 'POST /api/mcp ohne Token: 401 mit der Adresse der Metadaten' },
    { from: 0, to: 2, label: 'Metadaten lesen, unter /oauth2/register registrieren' },
    { from: 0, to: 1, label: '/oauth2/authorize mit PKCE-Challenge öffnen' },
    { from: 1, to: 2, label: 'Anmelden, mit Code oder Passwort zustimmen' },
    { from: 2, to: 0, label: 'Code an http://localhost:<Port>/callback' },
    { from: 0, to: 2, label: 'Code unter /oauth2/token tauschen' },
    { from: 0, to: 2, label: '/api/mcp mit dem Zugriffstoken' },
  ]}
  caption="Der Client findet alles selbst. Er braucht nur die MCP-Adresse."
/>

- **Erkennung.** Eine Anfrage ohne Token bekommt `401` mit `WWW-Authenticate: Bearer resource_metadata="..."`. Die Metadaten (`/.well-known/oauth-protected-resource/api/mcp`) nennen nexxus als Autorisierungsserver, dessen Metadaten wiederum den Registrierungsendpunkt und den Scope `mcp`.
- **Tokens.** Das Zugriffstoken gilt 1 Stunde, das Refresh-Token 30 Tage. Jede Erneuerung ersetzt das Refresh-Token, das alte gilt dann nicht mehr. nexxus speichert beide nur als SHA-256-Prüfsumme und schlägt das Zugriffstoken bei jeder Anfrage nach. Deshalb wirken Trennen und Ausschalten sofort, und ein Neustart von nexxus meldet niemanden ab.
- **Rechte.** Jede Anfrage läuft als die Person hinter dem Token. Aktionen und das Lesen von Datensätzen prüfen dasselbe wie die Seiten der Anwendung.
- **Ergebnisse.** Datumsangaben kommen im ISO-Format, etwa `2026-12-28`.

| Adresse | Zweck |
|---|---|
| `/api/mcp` | Der MCP-Endpunkt (POST; DELETE beendet eine Sitzung) |
| `/.well-known/oauth-protected-resource/api/mcp` | Welchen Autorisierungsserver und Scope der MCP-Endpunkt verwendet (RFC 9728) |
| `/.well-known/oauth-authorization-server` | Die Metadaten des Autorisierungsservers (RFC 8414) |
| `/oauth2/register` | Selbstregistrierung des Clients (RFC 7591) |
| `/oauth2/authorize`, `/oauth2/consent`, `/oauth2/token` | Anmeldung, Zustimmung, Tokens |

## Wenn etwas schiefgeht

| Was Sie sehen | Ursache und Abhilfe |
|---|---|
| Die Zustimmungsseite sagt „Externe KI-Clients sind in dieser Organisation nicht freigeschaltet.“ und bietet kein <Ui>Verbinden</Ui> | Externe KI-Clients sind ausgeschaltet. Eine Administratorin oder ein Administrator schaltet sie ein, siehe Schritt 1. |
| Ein verbundener Client bekommt plötzlich jede Anfrage mit demselben Satz abgewiesen | Externe KI-Clients wurden ausgeschaltet. |
| „Das Passwort ist falsch.“ oder „Der Code ist ungültig oder es gab zu viele Versuche.“ auf der Zustimmungsseite | Der Nachweis für die Verbindung war falsch. Geben Sie ihn noch einmal ein. |
| Claude Code bittet unter `/mcp` um eine neue Anmeldung für `nexxus` | Die Verbindung wurde getrennt, oder das Refresh-Token ist nach 30 Tagen abgelaufen. Wählen Sie wieder <Ui>Authenticate</Ui>. |
| Der Client meldet „Diese Aktion braucht die Bestätigung der Person, aber dieser MCP-Client kann keine Rückfragen stellen (MCP elicitation).“ | Der Client kann Sie nicht fragen, also hat nexxus die Änderung nicht ausgeführt. Nehmen Sie einen Client mit Elicitation oder ändern Sie es in der Anwendung. |
| Die Registrierung scheitert mit `invalid_redirect_uri` | Der Client will den Anmeldecode an eine Adresse schicken, die weder auf Ihrem Rechner liegt noch vom Betrieb erlaubt ist. |

:::note[Für Selbstbetreiber]
| Einstellung | Zweck |
|---|---|
| `NEXXUS_SSO_ISSUER` | Die öffentliche HTTPS-Adresse des Backends. Die MCP-Adresse ist dieser Wert plus `/api/mcp`, und die Tokens sind daran gebunden. Setzen Sie sie in jeder ausgerollten Installation. |
| `nexxus.mcp.oauth.redirect-uris` | Rücksprungadressen außer dem eigenen Rechner der Person, die Clients registrieren dürfen, exakt verglichen. Standard: die beiden Adressen von claude.ai oben. |
| `nexxus.mcp.oauth.access-token-ttl` | Lebensdauer der Zugriffstokens. Standard `PT1H` |
| `nexxus.mcp.oauth.refresh-token-ttl` | Lebensdauer der Refresh-Tokens. Standard `P30D` |
:::

## Wie es weitergeht

<CardGrid>
  <LinkCard title="Mit Claude Code arbeiten" description="Was Sie fragen können, wie Änderungen bestätigt werden, und die Grenzen." href="/de/mcp/usage/" />
  <LinkCard title="MCP-Werkzeuge" description="Die Werkzeuge eines verbundenen Clients, nach Bereichen." href="/de/mcp/tools/" />
  <LinkCard title="Anmeldung und OAuth" description="Wie sich Personen anmelden, und was OAuth in nexxus sonst noch bedeutet." href="/de/setup/sign-in/" />
  <LinkCard title="Sicherheit" description="Zwei-Faktor-Anmeldung, Sitzungen und persönliche API-Tokens." href="/de/setup/security/" />
</CardGrid>