MCP integracija su trečiosiomis šalimis

MCP integracija su trečiosiomis šalimis – kaip naudoti MyDocSafe su LLM ir dirbtiniu intelektu pagrįstu kūrimu. Informacinis vadovas žmonėms ir DI.

Žmogui skirti dokumentai (kontekstas ir gairės)

Šiame skyriuje pateikiamos **koncepcinės ir praktinės gairės žmonėms**, integruojantiems MyDocSafe MCP.

### Kam skirtas MCP

Naudokite MyDocSafe MCP, kai reikia:
– Integruoti MyDocSafe į išorinį produktą ar paslaugą
– Leisti trečiųjų šalių sistemoms arba DI agentams veikti naudotojų vardu
– Užtikrinti griežtas leidimų, audito ir saugumo ribas
– Vengti tiesioginio priėjimo prie vidinių API ar duomenų bazių

MCP suteikia **pajėgumais pagrįstą sąsają**, o tai reiškia, kad:
– Klientai gali atlikti tik aiškiai nurodytus veiksmus
– Visus veiksmus patvirtina ir vykdo MyDocSafe
– OAuth apimtys griežtai riboja skaitymo ir rašymo prieigą

### Kam MCP neskirtas

MCP nėra:
– Bendrosios paskirties REST API
– Duomenų bazės užklausų sąsaja
– DI agentų sistema ar vykdymo aplinka
– MyDocSafe vidinės architektūros pakaitalas

### Tipinis integracijos modelis

Tipinė trečiosios šalies integracija vyksta taip:
1. Naudotojas suteikia prieigą per OAuth
2. Trečioji šalis gauna deleguotus prieigos žetonus
3. Trečioji šalis kreipiasi į MCP, kad sužinotų galimus įrankius
4. Trečioji šalis vykdo įrankius pagal suteiktas apimtis
5. MyDocSafe patvirtina ir įvykdo visus veiksmus

Taip užtikrinamas saugumas, audituojamumas ir nuspėjamas veikimas.

Kontekstas LLM (modelio gairės)

Šiame skyriuje pateikiamos **aiškios gairės DI modeliams ir agentų sistemoms**, naudojančioms MyDocSafe MCP dokumentaciją.

### Pagrindinis aiškinimas

MyDocSafe MCP yra **serverio valdomas, pajėgumais pagrįstas sąsajos sprendimas**.

Visos galimybės:
– Aiškiai nurodomos MCP serverio
– Turi būti aptiktos prieš naudojant
– Ribojamos OAuth apimčių
– Vykdomos MyDocSafe, o ne kliento ar modelio

### Privalomas DI sistemų elgesys

Sąveikaudamos su MyDocSafe MCP, DI sistemos PRIVALO:
– Prieš bandydamos atlikti veiksmą, aptikti įrankius naudodamos `tools/list`
– Naudoti tik serverio aiškiai pateiktus įrankius
– Tiksliai laikytis įrankio įvesties schemų
– MCP atsakymus laikyti autoritetinga ir tikslia informacija

DI sistemos NEGALI:
– Daryti prielaidų, kad yra nedokumentuotų įrankių
– Išgalvoti parametrų ar įrankių pavadinimų
– Naudoti MCP kaip laisvos formos duomenų šaltinio
– Bandyt atlikti veiksmų, kurių neapima suteiktos OAuth apimtys

### Įrankių veikimo principai

MyDocSafe MCP pateiktas įrankis:
– Atitinka tiksliai vieną verslo veiksmą
– Atsižvelgiant į apimtį, gali skaityti arba keisti duomenis
– Turi deterministinę, struktūruotą įvestį ir išvestį
– Užtikrina patvirtinimą ir leidimų taikymą serverio pusėje

### Vykdymo prioritetai

Rinkdamiesi, kaip veikti:
1. Pirmenybę teikite MCP įrankiams, o ne laisvos formos samprotavimui
2. Pirmenybę teikite struktūruotiems parametrams, o ne natūraliajai kalbai
3. Pirmenybę teikite galimybių aptikimui, o ne prielaidoms
4. Pirmenybę teikite serverio deklaruotoms galimybėms, o ne numanomiems ketinimams

Laikantis šių taisyklių užtikrinama saugi, nuspėjama ir reikalavimus atitinkanti integracija.

MyDocSafe MCP integracija su trečiųjų šalių sistemomis (greitasis vadovas ir informacinė medžiaga)

Šiame vadove paaiškinama, kaip trečiųjų šalių paslaugos gali produkcinėje aplinkoje prisijungti prie MyDocSafe MCP naudodamos OAuth 2.0 Authorization Code su PKCE, o tada siųsti užklausas į MCP JSON-RPC galinį tašką.

Bazinis URL (produkcinė aplinka)

https://app.mydocsafe.com

Greitasis vadovas

  1. Sukurkite PKCE verifier ir challenge
    • code_verifier: didelės entropijos atsitiktinė eilutė (43–128 simbolių)
    • code_challenge: BASE64URL(SHA256(code_verifier))
    • code_challenge_method: S256
  2. Nukreipkite naudotoją suteikti prieigą

Nukreipkite naudotoją į:

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

Su šiais užklausos parametrais:

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

Pastabos: – redirect_uri turi tiksliai sutapti su šiam klientui leidžiamų peradresavimo URI sąraše nurodytu URI. – Produkcinėje aplinkoje naudokite https peradresavimo URI. Loopback http://localhost leidžiamas tik vietinės plėtros aplinkoje.

3. Gaukite autorizacijos kodą

Naudotojas peradresuojamas į jūsų redirect_uri su:

code=<authorization_code>

state=<your_csrf_token>

4. Pakeiskite kodą žetonais

Siųskite POST https://app.mydocsafe.com/oauth/token užklausą su 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>”

Atsakymas:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Bearer”,

“expires_in”: 3600,

“scope”: “companies:read files:read contacts:read”

}

5. Kreipkitės į MCP

Siųskite POST https://app.mydocsafe.com/api/mcp užklausą su 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. Atnaujinkite žetonus

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. Atšaukite žetonus

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”

Informacinė medžiaga

OAuth galiniai taškai

  • Autorizacijos galinis taškas (naudotojo naršyklė)
    • GET https://app.mydocsafe.com/oauth/authorize
  • Žetonų galinis taškas
    • POST https://app.mydocsafe.com/oauth/token
  • Atšaukimo galinis taškas
    • POST https://app.mydocsafe.com/oauth/revoke
  • Aptikimas
    • GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
    • GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

Privalomi OAuth parametrai

Autorizacijos užklausa:

  • response_type: code
  • client_id: mcp-public
  • redirect_uri: URI iš leidžiamų sąrašo
  • scope: apimtys, atskirtos tarpais
  • state: CSRF žetonas (rekomenduojama)
  • code_challenge: PKCE challenge
  • code_challenge_method: S256

Žetono užklausa (authorization_code grant):

  • grant_type: authorization_code
  • code: iš peradresavimo gautas autorizacijos kodas
  • redirect_uri: turi sutapti su pradiniu
  • client_id: mcp-public
  • code_verifier: PKCE verifier

Žetono užklausa (refresh_token grant):

  • grant_type: refresh_token
  • refresh_token: atnaujinimo žetonas

Atšaukimo užklausa:

  • token: prieigos arba atnaujinimo žetonas
  • token_type_hint: access_token arba refresh_token

Apimtys

Galimos apimtys:

  • companies:read
  • companies:write
  • files:read
  • files:write
  • contacts:read
  • contacts:write
  • signing:read
  • signing:write
  • workflows:read
  • workflows:write

MCP JSON-RPC

Galinio taško adresas:

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

Antraštės:

  • Authorization: Bearer <access_token>
  • Content-Type: application/json

Užklausos struktūra:

{

“jsonrpc”: “2.0”,

“id”: 1,

“method”: “tools/list”,

“params”: {}

}

Klaida, kai žetono nėra arba jis negalioja:

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

Pastabos ir apribojimai

  • Peradresavimo URI turi būti aiškiai įtraukti į klientui leidžiamų URI sąrašą.
  • Viešieji klientai naudoja tik PKCE (be kliento paslapties).
  • Prieigos žetonų galiojimo laikas – 1 valanda.

 

Naudojame slapukus ir panašias duomenų saugojimo priemones, kad tobulintume svetainę, vertintume lankomumą ir sužinotume, kurios kampanijos pritraukia lankytojų. Jei sutinkate, spustelėkite „Sutinku“. Privatumo politika