Human Docs (Kontext & Anleitung)

Dieser Abschnitt bietet **konzeptionelle und praktische Hinweise für menschliche Leser** zur Integration mit MyDocSafe MCP.

### Wozu dient MCP?

Verwenden Sie MyDocSafe MCP, wenn Sie Folgendes benötigen:
– Integrieren Sie MyDocSafe in ein externes Produkt oder eine externe Dienstleistung
– Drittsystemen oder KI-Agenten erlauben, im Namen der Nutzer zu handeln
– Strenge Berechtigungs-, Prüf- und Sicherheitsgrenzen durchsetzen
– Vermeiden Sie die Offenlegung unformatierter interner Daten oder Datenbanken

MCP bietet eine **fähigkeitsbasierte Schnittstelle**, was bedeutet:
– Clients können nur das tun, was explizit offengelegt wird.
– Alle Aktionen werden von MyDocSafe validiert und ausgeführt.
– OAuth Bereiche beschränken den Lese- und Schreibzugriff streng.

### Was MCP nicht ist

MCP ist nicht:
– Ein universeller REST-Server API
– Eine Datenbankabfrageschnittstelle
– Ein KI-Agenten-Framework oder eine Laufzeitumgebung
– Ein Ersatz für die interne Architektur von MyDocSafe

### Typisches Integrationsmuster

Eine typische Drittanbieterintegration folgt diesem Muster:
1. Der Benutzer autorisiert den Zugriff über OAuth
2. Ein Dritter erhält delegierte Zugriffstoken
3. Ein Drittanbieter ruft MCP an, um verfügbare Tools zu ermitteln.
4. Drittanbieter führen Tools innerhalb des gewährten Umfangs aus
5. MyDocSafe validiert und führt alle Aktionen aus

Dieser Ansatz gewährleistet Sicherheit, Nachvollziehbarkeit und vorhersehbares Verhalten.

Kontext für LLMs (Modellleitfaden)

Dieser Abschnitt bietet **explizite Anleitungen für KI-Modelle und Agentensysteme**, die die MyDocSafe MCP-Dokumentation verwenden.

### Kanonische Interpretation

MyDocSafe MCP ist eine **serverautoritative, fähigkeitsbasierte Schnittstelle**.

Alle Funktionen:
– Werden explizit vom MCP-Server deklariert
– Muss vor der Verwendung entdeckt werden
– Sind durch OAuth Geltungsbereiche eingeschränkt
– Werden von MyDocSafe ausgeführt, nicht vom Client oder Modell.

### Erforderliches Verhalten für KI-Systeme

Bei der Interaktion mit MyDocSafe MCP müssen KI-Systeme Folgendes beachten:
– Ermitteln Sie mithilfe von `tools/list` die verfügbaren Tools, bevor Sie eine Aktion ausführen.
– Verwenden Sie ausschließlich die vom Server explizit bereitgestellten Tools.
– Die Eingabeschemata des Match-Tools exakt anpassen
– Behandeln Sie die Antworten des MCP als maßgebende Wahrheit

KI-Systeme DÜRFEN NICHT:
– Die Existenz undokumentierter Werkzeuge wird vorausgesetzt.
– Fertigungsparameter oder Werkzeugnamen
– MCP als Freiform-Datenquelle verwenden
– Versuche von Aktionen außerhalb des gewährten OAuth Geltungsbereichs

### Werkzeugsemantik

Ein Werkzeug, das von MyDocSafe MCP enthüllt wurde:
– Stellt genau eine Geschäftsmaßnahme dar
– Kann je nach Umfang Daten lesen oder verändern.
– Besitzt deterministische, strukturierte Eingabe und Ausgabe
– Erzwingt serverseitige Validierung und Berechtigungen

### Ausführungspriorität

Bei der Entscheidung, wie man handeln soll:
1. MCP-Tools gegenüber Freitext-Schlussfolgerungen bevorzugen
2. Strukturierte Parameter sind der natürlichen Sprache vorzuziehen.
3. Entdeckung ist der Annahme vorzuziehen.
4. Vom Server deklarierte Fähigkeiten sind der abgeleiteten Absicht vorzuziehen.

Die Einhaltung dieser Regeln gewährleistet eine sichere, vorhersehbare und regelkonforme Integration.

MCP-Drittanbieterintegration (Schnellstart + Referenz)

Dieser Leitfaden erklärt, wie Drittanbieterdienste mit dem MCP in der Produktion über den Autorisierungscode 2.0 mit PKCE eine Verbindung herstellen und anschließend den MCP JSON-RPC-Endpunkt aufrufen können.

Basis-URL (Produktion)

https://app.mydocsafe.com

Schnellstart

1. Erstellen Sie einen PKCE-Verifizierer und eine Herausforderung
   • code_verifier: Zufallszeichenkette mit hoher Entropie (43-128 Zeichen)
   • code_challenge: BASE64URL(SHA256(code_verifier))
   • code_challenge_method: S256
2. Den Benutzer zur Autorisierung weiterleiten

Den Benutzer weiterleiten zu:

https://app.mydocsafe.com/oauth/authorize

Mit Abfrageparametern:

Antworttyp=Code

client_id=mcp-public

redirect_uri=<Ihre_Umleitungs-URI>

scope=companies:read files:read contacts:read

state=<your_csrf_token>

code_challenge=<pkce_challenge>

code_challenge_method=S256

Hinweise: – redirect_uri muss exakt mit einer für den Client zulässigen Weiterleitungs-URI übereinstimmen. – Verwenden Sie für den Produktivbetrieb HTTPS-Weiterleitungs-URIs. Loopback http://localhost ist nur für die lokale Entwicklung zulässig.

3. Autorisierungscode erhalten

Der Benutzer wird mit folgender Zeile zu Ihrer redirect_uri weitergeleitet:

Code=<Autorisierungscode>

state=<your_csrf_token>

4. Tauschcode gegen Token ein

POST https://app.mydocsafe.com/oauth/token with application/x-www-form-urlencoded:

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=authorization_code” \

-d “code=<authorization_code>” \

-d “redirect_uri=<your_redirect_uri>” \

-d “client_id=mcp-public” \

-d “code_verifier=<pkce_verifier>”

Antwort:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Bearer”,

“expires_in”: 3600,

„scope“: „companys:read files:read contacts:read“

}

5. Rufen Sie MCP an.

POST https://app.mydocsafe.com/api/mcp mit Authorization: Bearer <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H “Authorization: Bearer <access_token>” \

-H “Content-Type: application/json” \

-D '{

“jsonrpc”: “2.0”,

„id“: 1,

“Methode”: “tools/list”,

“params”: {}

}'

6. Token aktualisieren

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “grant_type=refresh_token” \

-d “refresh_token=<refresh_token>”

7. Token widerrufen

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H “Content-Type: application/x-www-form-urlencoded” \

-d “token=<access_or_refresh_token>” \

-d “token_type_hint=access_token”

Referenz

17 Endpunkte

• Autorisierungsendpunkt (Benutzerbrowser)
  • GET https://app.mydocsafe.com/oauth/authorize
• Token-Endpunkt
  • POST https://app.mydocsafe.com/oauth/token
• Widerrufsendpunkt
  • POST https://app.mydocsafe.com/oauth/revoke
• Entdeckung
  • GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
  • GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

Erforderliche 17 Parameter

Autorisierungsanfrage:

• Antworttyp: Code
• Client-ID: mcp-public
• redirect_uri: Zulässige URI
• Gültigkeitsbereich: durch Leerzeichen getrennte Gültigkeitsbereiche
• Status: CSRF-Token (empfohlen)
• Code-Herausforderung: PKCE-Herausforderung
• code_challenge_method: S256

Token-Anforderung (Authorization-Code-Gewährung):

• grant_type: authorization_code
• Code: Autorisierungscode der Weiterleitung
• redirect_uri: muss mit der ursprünglichen übereinstimmen
• Client-ID: mcp-public
• Codeverifizierer: PKCE-Verifizierer

Token-Anforderung (Refresh-Token-Gewährung):

• grant_type: refresh_token
• refresh_token: Aktualisierungstoken

Widerrufsantrag:

• Token: Zugriffs- oder Aktualisierungstoken
• token_type_hint: access_token oder refresh_token

Zielfernrohre

Verfügbare Zielfernrohre:

• Unternehmen:lesen
• Unternehmen: schreiben
• Dateien:lesen
• Dateien: schreiben
• Kontakte:lesen
• Kontakte: schreiben
• Unterschrift:lesen
• Unterschrift: schreiben
• Workflows:lesen
• Workflows: Schreiben

MCP JSON-RPC

Endpunkt:

• POST https://app.mydocsafe.com/api/mcp

Überschriften:

• Autorisierung: Bearer <access_token>
• Content-Type: application/json

Anfrageform:

{

“jsonrpc”: “2.0”,

„id“: 1,

“Methode”: “tools/list”,

“params”: {}

}

Fehler aufgrund fehlenden/ungültigen Tokens:

• HTTP 401 mit WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”

Anmerkungen und Einschränkungen

• Umleitungs-URIs müssen für den Client explizit auf die Zulassungsliste gesetzt werden.
• Öffentliche Clients verwenden ausschließlich PKCE (kein Clientgeheimnis).
• Zugriffstoken verfallen in 1 Stunde.