MCP-i kolmanda osapoole integratsioon
MCP-i kolmanda osapoole integratsioon – kuidas kasutada MyDocSafe’i LLM-ide ja tehisintellektil põhineva arendusega. Teatmik inimestele ja tehisintellektile.
Inimloetav dokumentatsioon (kontekst ja juhised)
See jaotis pakub MyDocSafe MCP-ga integreeruvatele inimlugejatele **kontseptuaalseid ja praktilisi juhiseid**.
### Milleks MCP on mõeldud
Kasutage MyDocSafe MCP-d, kui soovite:
– integreerida MyDocSafe välise toote või teenusega
– võimaldada kolmandate osapoolte süsteemidel või tehisintellekti agentidel kasutajate nimel tegutseda
– jõustada rangeid õiguste, kontrolljälje ja turvalisuse piire
– vältida sisemiste API-de või andmebaaside otseavamist
MCP pakub **võimekuspõhist liidest**, mis tähendab järgmist:
– kliendid saavad teha ainult seda, mis on selgesõnaliselt võimaldatud
– MyDocSafe valideerib ja teostab kõik toimingud
– OAuthi ulatused piiravad rangelt lugemis- ja kirjutamisõigust
### Milleks MCP ei ole mõeldud
MCP ei ole:
– üldotstarbeline REST API
– andmebaasipäringute liides
– tehisintellekti agendiraamistik ega käituskeskkond
– MyDocSafe’i sisearhitektuuri asendus
### Tüüpiline integratsioonimuster
Tüüpiline kolmanda osapoole integratsioon toimib järgmiselt:
1. Kasutaja annab OAuthi kaudu juurdepääsuloa
2. Kolmas osapool saab delegeeritud juurdepääsutõendid
3. Kolmas osapool kutsub MCP-d saadaolevate tööriistade tuvastamiseks
4. Kolmas osapool kasutab tööriistu antud ulatuste piires
5. MyDocSafe valideerib ja teostab kõik toimingud
See lahendus tagab turvalisuse, auditeeritavuse ja prognoositava käitumise.
Kontekst LLM-idele (mudeli juhised)
See jaotis sisaldab **selgesõnalisi juhiseid tehisintellekti mudelitele ja agendisüsteemidele**, mis kasutavad MyDocSafe MCP dokumentatsiooni.
### Põhitõlgendus
MyDocSafe MCP on **serveri autoriteediga, võimekuspõhine liides**.
Kõik võimalused:
– määrab selgesõnaliselt MCP server
– tuleb enne kasutamist tuvastada
– on piiratud OAuthi ulatustega
– teostab MyDocSafe, mitte klient ega mudel
### Tehisintellektisüsteemidele kohustuslik käitumine
MyDocSafe MCP-ga suheldes PEAVAD tehisintellektisüsteemid:
– enne mis tahes toimingu proovimist tuvastama tööriistad käsuga `tools/list`
– kasutama ainult serveri selgesõnaliselt avaldatud tööriistu
– järgima täpselt tööriista sisendskeeme
– käsitlema MCP vastuseid autoriteetse tõeallikana
TehisintellektisüsteemID EI TOHI:
– eeldada dokumenteerimata tööriistade olemasolu
– fabritseerida parameetreid ega tööriistade nimesid
– kasutada MCP-d vabas vormis andmeallikana
– proovida toiminguid väljaspool antud OAuthi ulatusi
### Tööriistade semantika
MyDocSafe MCP kaudu avaldatud tööriist:
– vastab täpselt ühele äritoimingule
– võib ulatusest sõltuvalt andmeid lugeda või muuta
– kasutab deterministlikku ja struktureeritud sisendit ning väljundit
– jõustab valideerimise ja õiguste kontrolli serveri poolel
### Täitmise prioriteedid
Tegutsemisviisi valimisel:
1. eelistage MCP tööriistu vabas vormis arutlusele
2. eelistage struktureeritud parameetreid loomulikule keelele
3. eelistage tuvastamist eeldamisele
4. eelistage serveri määratud võimekust järeldatud kavatsusele
Nende reeglite järgimine tagab turvalise, prognoositava ja nõuetele vastava integratsiooni.
MCP kolmanda osapoole integratsioon (kiirjuhend ja viited)
See juhend selgitab, kuidas kolmandate osapoolte teenused saavad tootmiskeskkonnas MyDocSafe MCP-ga ühenduda, kasutades OAuth 2.0 Authorization Code’i koos PKCE-ga, ning seejärel kutsuda MCP JSON-RPC lõpp-punkti.
Põhi-URL (tootmiskeskkond)
https://app.mydocsafe.com
Kiirjuhend
- Looge PKCE kontrollväärtus ja väljakutse
- code_verifier: suure entroopiaga juhuslik string (43–128 märki)
- code_challenge: BASE64URL(SHA256(code_verifier))
- code_challenge_method: S256
- Suunake kasutaja autoriseerimiseks edasi
Suunake kasutaja aadressile:
https://app.mydocsafe.com/oauth/authorize
Päringuparameetritega:
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
Märkused: – redirect_uri peab täpselt vastama kliendi lubatud ümbersuunamise URI-le. – Tootmiskeskkonnas kasutage https ümbersuunamise URI-sid. Loopback-aadress http://localhost on lubatud ainult kohalikus arenduskeskkonnas.
3. Saate autoriseerimiskoodi
Kasutaja suunatakse teie redirect_uri aadressile, kaasas:
code=<authorization_code>
state=<your_csrf_token>
4. Vahetage kood tõendite vastu
POST https://app.mydocsafe.com/oauth/token päisega 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>”
Vastus:
{
“access_token”: “….”,
“refresh_token”: “….”,
“token_type”: “Bearer”,
“expires_in”: 3600,
“scope”: “companies:read files:read contacts:read”
}
5. Kutsuge MCP-d
POST https://app.mydocsafe.com/api/mcp päisega 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. Värskendage tõendeid
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. Tühistage tõendid
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”
Viited
OAuthi lõpp-punktid
- Autoriseerimise lõpp-punkt (kasutaja brauser)
- GET https://app.mydocsafe.com/oauth/authorize
- Tõendi lõpp-punkt
- POST https://app.mydocsafe.com/oauth/token
- Tühistamise lõpp-punkt
- POST https://app.mydocsafe.com/oauth/revoke
- Avastamine
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource
Nõutavad OAuthi parameetrid
Autoriseerimispäring:
- response_type: code
- client_id: mcp-public
- redirect_uri: lubatud URI
- scope: tühikutega eraldatud ulatused
- state: CSRF-tõend (soovitatav)
- code_challenge: PKCE väljakutse
- code_challenge_method: S256
Tõendipäring (authorization_code grant):
- grant_type: authorization_code
- code: ümbersuunamise kaudu saadud autoriseerimiskood
- redirect_uri: peab vastama algsele URI-le
- client_id: mcp-public
- code_verifier: PKCE kontrollväärtus
Tõendipäring (refresh_token grant):
- grant_type: refresh_token
- refresh_token: värskendustõend
Tühistamispäring:
- token: juurdepääsu- või värskendustõend
- token_type_hint: access_token või refresh_token
Ulatused
Saadaolevad ulatused:
- companies:read
- companies:write
- files:read
- files:write
- contacts:read
- contacts:write
- signing:read
- signing:write
- workflows:read
- workflows:write
MCP JSON-RPC
Lõpp-punkt:
- POST https://app.mydocsafe.com/api/mcp
Päised:
- Authorization: Bearer <access_token>
- Content-Type: application/json
Päringu struktuur:
{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “tools/list”,
“params”: {}
}
Viga puuduva või kehtetu tõendi korral:
- HTTP 401 koos päisega WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”
Märkused ja piirangud
- Ümbersuunamise URI-d peavad olema kliendi jaoks selgesõnaliselt lubatud.
- Avalikud kliendid kasutavad ainult PKCE-d (kliendi saladust ei kasutata).
- Juurdepääsutõendid aeguvad 1 tunni pärast.