> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novaplan.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Novaplan AI is a workplace AI platform: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations.
> When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {NOVAPLAN_WORKSPACE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline.
> Start at https://docs.novaplan.ai/for-agents.md. Client setup: https://docs.novaplan.ai/mcp/overview.md. QM is not an MCP client: https://docs.novaplan.ai/mcp/qm.md.
> Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login.
> Never print, log, or ask anyone to paste a Novaplan AI token.
# MCP-Server im Überblick
> MCP-Clients über OAuth oder ein persönliches Zugriffstoken mit Novaplan AI verbinden.
## Was ist der Novaplan AI MCP-Server?
Novaplan AI stellt unter `/mcp` einen **entfernten MCP-Endpunkt** über **Streamable HTTP** bereit. MCP-Clients verbinden sich direkt mit diesem Endpunkt; für diese Verbindung sind weder ein lokales npm-Paket noch ein stdio-Prozess erforderlich.
Damit können Clients wie **Cursor**, **Claude Code**, **Gemini CLI**, **Claude.ai**, **LibreChat** und **Omnigent** indexierte Dokumente Ihrer Organisation durchsuchen, Fragen dazu stellen, Personen und Gruppen finden sowie Dateien herunterladen.
Die einzelnen verfügbaren Werkzeuge, Argumente und Einsatzfälle stehen in der [Werkzeugreferenz](/de/mcp/tools). Die [Anleitung für Coding-Agenten](/de/for-agents) bietet einen Einstieg für Entwicklungsumgebungen.
**[QM](/de/mcp/qm) ist kein MCP-Client.** Die Integration verwendet eine CLI im Agenten-Sandbox-Prozess. Die bestehende technische Anleitung enthält den dazugehörigen Befehl.
## Voraussetzungen
* Zugang zu einem bestehenden Novaplan AI Workspace und seiner Adresse. Falls der Zugang noch nicht eingerichtet ist, wenden Sie sich an [Novaplan Support](/de/contact-us).
* Entweder eine OAuth-Anwendung oder ein [persönliches Zugriffstoken](/de/developer/personal-access-tokens), abhängig vom Client.
Novaplan übernimmt den Großteil der Einrichtung. Die folgenden Schritte bleiben als Referenz für Administratoren und Integrationsverantwortliche verfügbar; stimmen Sie Änderungen an der Zugriffsverwaltung mit dem Novaplan-Team ab.
Die meisten unten genannten Client-Anleitungen verwenden **OAuth** und benötigen eine OAuth-Anwendung. **Claude Code** und **Omnigent** können sich stattdessen mit einem persönlichen Zugriffstoken im `Authorization`-Header verbinden. Claude Code unterstützt weiterhin eine OAuth-Anwendung für gemeinsam verwaltete Einrichtungen.
Für eigene Werkzeuge können Sie unter **Developer Settings > Personal Access Tokens** ein Token erstellen und es als `Bearer`-Token verwenden: direkt am `/mcp`-Endpunkt, mit `--bearer-auth` in der [lokalen Stdio-Brücke](/de/mcp/local-server) oder in einem Client mit konfigurierbarem `Authorization`-Header.
## Schritt 1: OAuth-Anwendung erstellen
Melden Sie sich mit einem Administratorkonto an und öffnen Sie **Settings > Developer Settings > OAuth Apps**.
Klicken Sie auf **Create OAuth App**. Geben Sie einen Namen ein, beispielsweise `MCP Integration`, und fügen Sie die Redirect-URIs der gewünschten Clients hinzu.
Speichern Sie die Anwendung und kopieren Sie **Client ID** und **Client Secret** an einen sicheren Ort.
### Redirect-URIs
Tragen Sie die URIs der Clients ein, die Sie verwenden möchten:
| Client | Redirect-URI |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Cursor Desktop** | `http://localhost:8787/callback`; ältere Installationen können `cursor://anysphere.cursor-mcp/oauth/callback` verwenden |
| **Cursor Web / Agents** | `https://www.cursor.com/agents/mcp/oauth/callback` |
| **Claude Code** | `http://localhost:/callback`, beispielsweise `http://localhost:8080/callback` |
| **Claude.ai (Web)** | `https://claude.ai/api/mcp/auth_callback` |
| **Claude Desktop** (Custom Connector) | `https://claude.ai/api/mcp/auth_callback` |
| **Gemini CLI** | `http://localhost:7777/oauth/callback`, wenn als `redirectUri` festgelegt; sonst wählt Gemini CLI einen zufälligen Port |
| **LibreChat** | `http://localhost:3080/api/mcp//oauth/callback` |
Die OAuth-Anwendung muss die vom Client tatsächlich angeforderten Scopes erlauben. Ein angeforderter Scope außerhalb der erlaubten Menge führt zu einem Autorisierungsfehler. Novaplan verwaltet die serverseitigen `MCP_SCOPES`-Standardwerte; wenn der Client eine freigegebene Teilmenge anfordert, muss die Anwendung nicht jeden bekannt gegebenen Scope erlauben.
### Standard-Scopes anpassen
Novaplan AI gibt über `/.well-known/oauth-protected-resource/mcp` standardmäßig Scopes für die automatische Erkennung bekannt. Novaplan kann diese serverseitigen Standardwerte mit `MCP_SCOPES` prüfen und anpassen. Claude Code kann zusätzlich mit `oauth.scopes` eine freigegebene Teilmenge anfordern; allein die Bekanntgabe eines Scopes bedeutet nicht, dass die OAuth-Anwendung alle katalogisierten Scopes erlauben muss.
Der zugängliche Quellcode und die Enterprise-Deployment-Vorlage verwenden den folgenden Standardkatalog. Das ist **keine** Empfehlung, jeder OAuth-Anwendung sämtliche Scopes zu gewähren. Prüfen Sie die vom Client angeforderten Scopes und die tatsächlich benötigten Werkzeuge:
```bash theme={null}
MCP_SCOPES=openid,profile,email,offline_access,semantic:write,conversation:write,conversation:chat,kb:read,team:read,user:read,config:read,agent:read,agent:execute,connector:read
```
## Platzhalter in den Beispielen
Ersetzen Sie die Platzhalter in den Client-Konfigurationen:
| Platzhalter | Bedeutung | Beispiel |
| ------------------------ | --------------------------------------------------------------------- | ------------------------------------ |
| `NOVAPLAN_WORKSPACE_URL` | Adresse Ihres Novaplan AI Workspaces. | `https://your-workspace.example.com` |
| `YOUR_CLIENT_ID` | Client ID der OAuth-Anwendung. | `clid_abc123...` |
| `YOUR_CLIENT_SECRET` | Client Secret der OAuth-Anwendung. | `clsec_xyz789...` |
| `YOUR_BEARER_TOKEN` | Persönliches Zugriffstoken für die lokale Stdio-Brücke oder Omnigent. | `phpat_eyJhbGci...` |
Der entfernte MCP-Endpunkt lautet `NOVAPLAN_WORKSPACE_URL/mcp`.
## Client-Anleitungen
Wählen Sie die Anleitung für Ihren Client:
| Client | Verbindung |
| -------------------------------------------- | ------------------------------------------------------------------------ |
| [Cursor](/de/mcp/cursor) | Entferntes MCP mit dem `auth`-Objekt in `mcp.json`. |
| [Claude Code](/de/mcp/claude-code) | Entferntes HTTP-MCP mit persönlichem Zugriffstoken oder OAuth-Anwendung. |
| [Gemini CLI](/de/mcp/gemini-cli) | Entferntes MCP mit OAuth-Erkennung. |
| [Claude.ai](/de/mcp/claude-ai) | Custom Connector in der Web-Oberfläche. |
| [Claude Desktop](/de/mcp/claude-desktop) | Gehosteter Custom Connector oder lokale Stdio-Brücke. |
| [LibreChat](/de/mcp/librechat) | Entferntes MCP über die Custom-Connectors-Oberfläche. |
| [Omnigent](/de/mcp/omnigent) | Verbindung über persönliches Zugriffstoken. |
| [Local Server (Stdio)](/de/mcp/local-server) | Lokale Stdio-Brücke. |
| [QM](/de/mcp/qm) | CLI in der Agenten-Sandbox; keine MCP-Verbindung. |
## Funktionsweise
### Architektur
```text theme={null}
KI-Client (Cursor, Claude Code, Gemini CLI, Claude.ai, LibreChat, Omnigent)
|
| HTTP POST (JSON-RPC)
| Authorization: Bearer
v
NOVAPLAN_WORKSPACE_URL/mcp
|
| Streamable HTTP, zustandslos pro Anfrage
v
Novaplan AI API (freigegebene Werkzeuge)
```
### OAuth Protected Resource Discovery
Novaplan AI stellt die OAuth-Erkennung unter folgender Adresse bereit:
```text theme={null}
NOVAPLAN_WORKSPACE_URL/.well-known/oauth-protected-resource/mcp
```
Darüber erhält der Client die OAuth-Endpunkte:
* Autorisierung: `NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/authorize`
* Token: `NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/token`
* Widerruf: `NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/revoke`
* JWKS: `NOVAPLAN_WORKSPACE_URL/.well-known/jwks.json`
## Fehlerbehebung
Der Client versucht eine dynamische Registrierung statt der vorbereiteten OAuth-Zugangsdaten. Prüfen Sie `--client-id` und `--client-secret` für Claude Code beziehungsweise das `auth`-Objekt für Cursor.
Die **Redirect URI** der OAuth-Anwendung muss exakt zur vom Client verwendeten URI passen. Prüfen Sie außerdem, ob die OAuth-Anwendung in Novaplan AI aktiv ist. Beispiele für die einzelnen Clients stehen in der Tabelle oben.
Prüfen Sie die Erreichbarkeit mit `curl -X POST NOVAPLAN_WORKSPACE_URL/mcp`. Ohne Token sollte der Server mit `401` antworten; ein Verbindungsfehler weist auf ein anderes Problem hin.
Starten Sie `npx @modelcontextprotocol/inspector` und verbinden Sie den Inspector mit `NOVAPLAN_WORKSPACE_URL/mcp` und einem Bearer-Token.
## Häufige Frage: Wie ändere ich Scopes?
1. Prüfen Sie, welche Scopes der Client tatsächlich anfordert. Claude Code kann mit `oauth.scopes` eine Teilmenge festlegen. Stimmen Sie eine Änderung von `MCP_SCOPES` nur dann mit Novaplan ab, wenn die serverseitig bekannt gegebenen Standardwerte geändert werden sollen.
2. Passen Sie die Scopes der OAuth-Anwendung unter **Settings > Developer Settings > OAuth Apps** an.
3. Verbinden Sie den Client erneut, da bestehende Tokens die bisherigen Scopes enthalten. Cursor kann neu hinzugefügt, Claude Code über `/mcp` erneut angemeldet und Claude.ai unter **Customize → Connectors** neu verbunden werden. Für Gemini CLI finden Sie den aktuellen Wiederanmeldungsbefehl in der [Client-Anleitung](/de/mcp/gemini-cli).