Integracija MCP-a s uslugama trećih strana
Integracija MCP-a s uslugama trećih strana – kako koristiti MyDocSafe s LLM-ovima i u razvoju temeljenom na AI-ju; referentni vodič za ljude i AI.
Ljudska dokumentacija (kontekst i smjernice)
Ovaj odjeljak pruža **konceptualne i praktične smjernice za ljudske čitatelje** koji se integriraju s MyDocSafe MCP-om.
### Čemu služi MCP
Upotrijebite MyDocSafe MCP kada trebate:
– Integrirati MyDocSafe u vanjski proizvod ili uslugu
– Omogućiti sustavima trećih strana ili AI agentima da djeluju u ime korisnika
– Provoditi stroga ograničenja dopuštenja, revizije i sigurnosti
– Izbjeći izlaganje internih API-ja ili baza podataka u sirovom obliku
MCP pruža **sučelje utemeljeno na mogućnostima**, što znači:
– Klijenti mogu učiniti samo ono što je izričito dostupno
– MyDocSafe provjerava i izvršava sve radnje
– OAuth opsezi strogo ograničavaju pristup za čitanje i pisanje
### Čemu MCP ne služi
MCP nije:
– REST API opće namjene
– Sučelje za upite prema bazi podataka
– Okvir ili okruženje za izvršavanje AI agenata
– Zamjena za internu arhitekturu MyDocSafea
### Uobičajeni obrazac integracije
Uobičajena integracija treće strane prati ovaj obrazac:
1. Korisnik odobrava pristup putem OAutha
2. Treća strana prima delegirane pristupne tokene
3. Treća strana poziva MCP kako bi otkrila dostupne alate
4. Treća strana izvršava alate u okviru dodijeljenih opsega
5. MyDocSafe provjerava i izvršava sve radnje
Ovim se pristupom osiguravaju sigurnost, mogućnost revizije i predvidljivo ponašanje.
Kontekst za LLM-ove (smjernice za modele)
Ovaj odjeljak pruža **izričite smjernice za AI modele i agentske sustave** koji upotrebljavaju dokumentaciju MyDocSafe MCP-a.
### Mjerodavno tumačenje
MyDocSafe MCP je **sučelje utemeljeno na mogućnostima, čijim upravljanjem mjerodavno upravlja poslužitelj**.
Sve mogućnosti:
– Poslužitelj MCP-a izričito navodi
– Moraju se otkriti prije upotrebe
– Ograničene su OAuth opsezima
– Izvršava ih MyDocSafe, a ne klijent ili model
### Obavezno ponašanje AI sustava
Pri interakciji s MyDocSafe MCP-om AI sustavi MORAJU:
– Otkriti alate pomoću `tools/list` prije pokušaja izvršavanja bilo koje radnje
– Upotrebljavati samo alate koje je poslužitelj izričito izložio
– Točno se pridržavati shema ulaznih podataka alata
– Smatrati odgovore MCP-a mjerodavnim izvorom istine
AI sustavi NE SMIJU:
– Pretpostavljati da postoje nedokumentirani alati
– Izmišljati parametre ili nazive alata
– Upotrebljavati MCP kao neograničeni izvor podataka
– Pokušavati izvršiti radnje izvan dodijeljenih OAuth opsega
### Semantika alata
Alat koji izlaže MyDocSafe MCP:
– Predstavlja točno jednu poslovnu radnju
– Može čitati ili mijenjati podatke, ovisno o opsegu
– Ima determinističke, strukturirane ulazne i izlazne podatke
– Provodi provjere valjanosti i dopuštenja na strani poslužitelja
### Prioritet izvršavanja
Pri odabiru načina djelovanja:
1. Dajte prednost alatima MCP-a u odnosu na zaključivanje na temelju slobodnog teksta
2. Dajte prednost strukturiranim parametrima u odnosu na prirodni jezik
3. Dajte prednost otkrivanju u odnosu na pretpostavke
4. Dajte prednost mogućnostima koje je naveo poslužitelj u odnosu na izvedene namjere
Pridržavanjem ovih pravila osiguravaju se sigurna, predvidljiva integracija usklađena s propisima.
Integracija MCP-a treće strane (brzi početak i referenca)
Ovaj vodič objašnjava kako se usluge trećih strana mogu u produkcijskom okruženju povezati s MyDocSafe MCP-om pomoću protokola OAuth 2.0 Authorization Code s PKCE-om, a zatim pozivati krajnju točku MCP JSON-RPC.
Osnovni URL (produkcija)
https://app.mydocsafe.com
Brzi početak
- Izradite PKCE verifikator i izazov
- code_verifier: nasumični niz visoke entropije (43 – 128 znakova)
- code_challenge: BASE64URL(SHA256(code_verifier))
- code_challenge_method: S256
- Preusmjerite korisnika na autorizaciju
Pošaljite korisnika na:
https://app.mydocsafe.com/oauth/authorize
S parametrima upita:
response_type=code
client_id=mcp-public
redirect_uri=<your_redirect_uri>
scope=companies:read files:read contacts:read
state=<your_csrf_token>
code_challenge=<pkce_challenge>
code_challenge_method=S256
Napomene: – redirect_uri mora se točno podudarati s URI-jem za preusmjeravanje na popisu dopuštenih URI-ja klijenta. – U produkciji upotrebljavajte https URI-je za preusmjeravanje. Loopback http://localhost dopušten je samo za lokalni razvoj.
3. Primite autorizacijski kod
Korisnik se preusmjerava na vaš redirect_uri s parametrima:
code=<authorization_code>
state=<your_csrf_token>
4. Zamijenite kod za tokene
POST https://app.mydocsafe.com/oauth/token s 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>”
Odgovor:
{
“access_token”: “….”,
“refresh_token”: “….”,
“token_type”: “Bearer”,
“expires_in”: 3600,
“scope”: “companies:read files:read contacts:read”
}
5. Pozovite MCP
POST https://app.mydocsafe.com/api/mcp s 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,
“method”: “tools/list”,
“params”: {}
}’
6. Osvježite tokene
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. Opozovite tokene
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”
Referenca
OAuth krajnje točke
- Krajnja točka za autorizaciju (korisnikov preglednik)
- GET https://app.mydocsafe.com/oauth/authorize
- Krajnja točka za tokene
- POST https://app.mydocsafe.com/oauth/token
- Krajnja točka za opoziv
- POST https://app.mydocsafe.com/oauth/revoke
- Otkrivanje
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource
Obavezni OAuth parametri
Zahtjev za autorizaciju:
- response_type: code
- client_id: mcp-public
- redirect_uri: URI s popisa dopuštenih
- scope: opsezi odvojeni razmacima
- state: CSRF token (preporučeno)
- code_challenge: PKCE izazov
- code_challenge_method: S256
Zahtjev za token (odobrenje authorization_code):
- grant_type: authorization_code
- code: autorizacijski kod iz preusmjeravanja
- redirect_uri: mora se podudarati s izvornim URI-jem
- client_id: mcp-public
- code_verifier: PKCE verifikator
Zahtjev za token (odobrenje refresh_token):
- grant_type: refresh_token
- refresh_token: token za osvježavanje
Zahtjev za opoziv:
- token: pristupni token ili token za osvježavanje
- token_type_hint: access_token ili refresh_token
Opsezi
Dostupni opsezi:
- companies:read
- companies:write
- files:read
- files:write
- contacts:read
- contacts:write
- signing:read
- signing:write
- workflows:read
- workflows:write
MCP JSON-RPC
Krajnja točka:
- POST https://app.mydocsafe.com/api/mcp
Zaglavlja:
- Authorization: Bearer <access_token>
- Content-Type: application/json
Struktura zahtjeva:
{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “tools/list”,
“params”: {}
}
Pogreška zbog nedostajućeg ili nevažećeg tokena:
- HTTP 401 s WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”
Napomene i ograničenja
- URI-ji za preusmjeravanje moraju biti izričito navedeni na popisu dopuštenih URI-ja klijenta.
- Javni klijenti upotrebljavaju samo PKCE (bez tajne klijenta).
- Pristupni tokeni istječu nakon 1 sata.