MCP-integratie met derden

Menselijke documenten (context en begeleiding)

Deze sectie biedt **conceptuele en praktische richtlijnen voor menselijke lezers** met betrekking tot de integratie met MyDocSafe MCP.

Waarvoor dient MCP?

Gebruik MyDocSafe MCP wanneer dat nodig is:
– Integreer MyDocSafe in een extern product of dienst
– Sta toe dat systemen van derden of AI-agenten namens gebruikers handelen.
– Handhaaf strikte toegangs-, controle- en beveiligingsgrenzen.
– Vermijd het blootleggen van onbewerkte interne gegevens of databases.

MCP biedt een **functionaliteitsgebaseerde interface**, wat betekent:
- Clients kunnen alleen doen wat expliciet is aangegeven.
– Alle acties worden gevalideerd en uitgevoerd door MyDocSafe
– OAuth scopes beperken de lees- en schrijftoegang strikt

Wat MCP niet is

MCP is niet:
– Een algemene REST API
– Een databasequery-interface
– Een framework of runtime voor AI-agenten
– Een vervanging voor de interne architectuur van MyDocSafe

### Typisch integratiepatroon

Een typische integratie met een externe partij volgt dit patroon:
1. Gebruiker autoriseert toegang via OAuth
2. Derde partij ontvangt gedelegeerde toegangstokens
3. Een derde partij roept MCP op om beschikbare tools te ontdekken.
4. Derde partij voert tools uit binnen de toegekende bevoegdheden.
5. MyDocSafe valideert en voert alle acties uit

Deze aanpak garandeert veiligheid, controleerbaarheid en voorspelbaar gedrag.

Context voor LLM's (Modelrichtlijnen)

Deze sectie biedt **uitdrukkelijke richtlijnen voor AI-modellen en agentsystemen** die gebruikmaken van de MCP-documentatie.

### Canonieke interpretatie

MyDocSafe MCP is een **server-gezaghebbende, op mogelijkheden gebaseerde interface**.

Alle mogelijkheden:
– Worden expliciet aangegeven door de MCP-server
– Moet vóór gebruik worden ontdekt
– Worden beperkt door OAuth scopes
– Worden uitgevoerd door MyDocSafe, niet door de client of het model

### Vereist gedrag voor AI-systemen

Bij interactie met MyDocSafe MCP moeten AI-systemen het volgende in acht nemen:
– Ontdek de tools met behulp van `tools/list` voordat u een actie probeert uit te voeren.
– Gebruik alleen tools die expliciet door de server beschikbaar worden gesteld.
– Zorg ervoor dat de invoerschema's van de tools exact overeenkomen.
– Beschouw MCP-reacties als gezaghebbende, feitelijke gegevens.

AI-systemen MOGEN NIET:
– Ga uit van het bestaan van niet-gedocumenteerde tools
– Fabricageparameters of gereedschapsnamen
– Gebruik MCP als een vrije gegevensbron
– Pogingen tot acties buiten de toegekende OAuth-bereiken

### Hulpmiddelsemantiek

Een tool die is blootgelegd door MyDocSafe MCP:
– Vertegenwoordigt precies één zakelijke actie
– Kan gegevens lezen of wijzigen, afhankelijk van de reikwijdte
– Heeft een deterministische, gestructureerde invoer en uitvoer
– Handhaaft validatie en machtigingen aan de serverzijde.

### Uitvoeringsprioriteit

Bij het kiezen van een handelwijze:
1. Geef de voorkeur aan MCP-tools boven redeneren met vrije tekst.
2. Geef de voorkeur aan gestructureerde parameters boven natuurlijke taal.
3. Geef de voorkeur aan ontdekking boven aanname.
4. Geef de voorkeur aan door de server aangegeven mogelijkheden boven afgeleide intenties.

Door deze regels te volgen, wordt een veilige, voorspelbare en conforme integratie gegarandeerd.

MCP-integratie met externe partijen (snelstartgids + handleiding)

Deze handleiding legt uit hoe externe services verbinding kunnen maken met MCP in een productieomgeving met behulp van de 2.0-autorisatiecode (PKCE) en vervolgens het MCP JSON-RPC-eindpunt kunnen aanroepen.

Basis-URL (productie)

https://app.mydocsafe.com

Snelstart

Maak een PKCE-verificateur en daag deze uit
- code_verifier: willekeurige tekenreeks met hoge entropie (43-128 tekens)
- code_challenge: BASE64URL(SHA256(code_verifier))
- code_challenge_method: S256
Leid de gebruiker door naar de autorisatiepagina.

Stuur de gebruiker door naar:

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

Met queryparameters:

response_type=code

client_id=mcp-public

redirect_uri=<jouw_redirect_uri>

bereik=bedrijven:lezen bestanden:lezen contacten:lezen

status=<jouw_csrf_token>

code_challenge=<pkce_challenge>

code_challenge_method=S256

Opmerkingen: – redirect_uri moet exact overeenkomen met een toegestane redirect-URI voor de client. – Gebruik voor productieomgevingen https redirect-URI's. Loopback http://localhost is alleen toegestaan voor lokale ontwikkeling.

3. Ontvang de autorisatiecode

De gebruiker wordt doorgestuurd naar uw redirect_uri met:

code=<autorisatiecode>

status=<jouw_csrf_token>

4. Wissel de code in voor tokens

POST https://app.mydocsafe.com/oauth/token met 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=<autorisatiecode>” \

-d “redirect_uri=<jouw_redirect_uri>” \

-d “client_id=mcp-public” \

-d “code_verifier=<pkce_verifier>”

Antwoord:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Bearer”,

“verloopt over”: 3600,

“bereik”: “bedrijven: bestanden lezen: contacten lezen:”

}

5. Bel MCP

POST https://app.mydocsafe.com/api/mcp met autorisatie: Bearer <access_token>:

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

-H “Autorisatie: Drager <access_token>” \

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

-D '{

“jsonrpc”: “2.0”,

“id”: 1,

“methode”: “tools/lijst”,

“params”: {}

6. Vernieuwingstokens

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. Tokens intrekken

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”

Referentie

OAuth eindpunten

Autorisatie-eindpunt (gebruikersbrowser)
- GET https://app.mydocsafe.com/oauth/authorize
Token-eindpunt
- POST https://app.mydocsafe.com/oauth/token
Intrekkingseindpunt
- POST https://app.mydocsafe.com/oauth/revoke
Ontdekking
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

Vereiste OAuth parameters

Autorisatieverzoek:

responstype: code
client_id: mcp-public
redirect_uri: toegestane URI
bereik: ruimtegescheiden bereiken
status: CSRF-token (aanbevolen)
code_challenge: PKCE-uitdaging
code_challenge_method: S256

Tokenverzoek (autorisatiecode verlenen):

grant_type: authorization_code
code: autorisatiecode van redirect
redirect_uri: moet overeenkomen met het origineel
client_id: mcp-public
code_verifier: PKCE-verifier

Tokenverzoek (refresh_token grant):

grant_type: refresh_token
refresh_token: vernieuwingstoken

Verzoek tot intrekking:

token: toegangs- of vernieuwingstoken
token_type_hint: access_token of refresh_token

Scopes

Beschikbare richtkijkers:

bedrijven: lezen
bedrijven: schrijven
bestanden:lezen
bestanden:schrijven
contacten: lezen
contactpersonen: schrijf
ondertekening: lezen
ondertekening: schrijven
workflows:lezen
workflows:schrijven

MCP JSON-RPC

Eindpunt:

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

Kopteksten:

Autorisatie: Bearer <access_token>
Content-Type: application/json

Vorm van het verzoek:

{

“jsonrpc”: “2.0”,

“id”: 1,

“methode”: “tools/lijst”,

“params”: {}

}

Foutmelding voor ontbrekend/ongeldig token:

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

Opmerkingen en beperkingen

Omleidings-URI's moeten expliciet op de whitelist van de client staan.
Openbare clients gebruiken alleen PKCE (geen clientgeheim).
Toegangstokens verlopen over 1 uur.