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

  1. 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
  2. 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.

 

Kasutame küpsiseid ja sarnaseid salvestustehnoloogiaid, et veebisaiti täiustada, mõõta külastatavust ning näha, millised kampaaniad toovad meile külastajaid. Sellega nõustumiseks klõpsa nupul „Nõustun“. Privaatsuspoliitika