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

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

 

Upotrebljavamo kolačiće i slične tehnologije pohrane kako bismo poboljšali web-mjesto, mjerili promet i saznali koje kampanje privlače posjetitelje. Kliknite „Prihvati” kako biste to dopustili. Pravila privatnosti