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