Integracija MCP z orodji tretjih oseb
Integracija MCP z orodji tretjih oseb – kako uporabljati MyDocSafe z LLM-i in pri razvoju z umetno inteligenco. Referenčni priročnik za ljudi in AI.
Človeška dokumentacija (kontekst in smernice)
Ta razdelek vsebuje **konceptualne in praktične smernice za človeške uporabnike**, ki se povezujejo z MyDocSafe MCP.
### Čemu je MCP namenjen
MyDocSafe MCP uporabite, kadar želite:
– Integrirati MyDocSafe v zunanji izdelek ali storitev
– Zunanjim sistemom ali agentom umetne inteligence omogočiti delovanje v imenu uporabnikov
– Zagotoviti strogo upoštevanje omejitev dovoljenj, revizije in varnosti
– Preprečiti razkrivanje neobdelanih notranjih API-jev ali zbirk podatkov
MCP zagotavlja **vmesnik, ki temelji na zmogljivostih**, kar pomeni:
– Odjemalci lahko izvajajo samo izrecno omogočena dejanja
– MyDocSafe preveri in izvede vsa dejanja
– Obsegi OAuth strogo omejujejo dostop za branje in pisanje
### Čemu MCP ni namenjen
MCP ni:
– Splošni REST API
– Vmesnik za poizvedovanje po zbirkah podatkov
– Ogrodje ali izvajalno okolje za agente umetne inteligence
– Nadomestilo za notranjo arhitekturo MyDocSafe
### Običajen vzorec integracije
Običajna integracija s tretjo stranjo poteka po naslednjem vzorcu:
1. Uporabnik odobri dostop prek OAuth
2. Tretja stran prejme delegirane žetone za dostop
3. Tretja stran pokliče MCP, da poišče razpoložljiva orodja
4. Tretja stran izvaja orodja v okviru dodeljenih obsegov
5. MyDocSafe preveri in izvede vsa dejanja
Ta pristop zagotavlja varnost, možnost revizije in predvidljivo delovanje.
Kontekst za LLM (smernice za modele)
Ta razdelek vsebuje **izrecne smernice za modele umetne inteligence in agentske sisteme**, ki uporabljajo dokumentacijo MyDocSafe MCP.
### Kanonična razlaga
MyDocSafe MCP je **vmesnik, ki ga upravlja strežnik in temelji na zmogljivostih**.
Vse zmogljivosti:
– Strežnik MCP jih izrecno določi
– Pred uporabo jih je treba odkriti
– Omejene so z obsegi OAuth
– Izvaja jih MyDocSafe, ne odjemalec ali model
### Zahtevano vedenje sistemov umetne inteligence
Pri uporabi MyDocSafe MCP MORAJO sistemi umetne inteligence:
– Pred poskusom katerega koli dejanja poiskati orodja z uporabo `tools/list`
– Uporabljati samo orodja, ki jih strežnik izrecno omogoča
– Natančno upoštevati sheme vhodnih podatkov orodij
– Odgovore MCP obravnavati kot avtoritativno dejansko stanje
Sistemi umetne inteligence NE SMEJO:
– Predpostavljati, da obstajajo nedokumentirana orodja
– Izmišljati si parametrov ali imen orodij
– Uporabljati MCP kot neomejen vir podatkov
– Poskušati izvajati dejanja zunaj dodeljenih obsegov OAuth
### Pomen orodij
Orodje, ki ga omogoča MyDocSafe MCP:
– Predstavlja natanko eno poslovno dejanje
– Lahko bere ali spreminja podatke, odvisno od obsega
– Ima deterministične in strukturirane vhodne ter izhodne podatke
– Na strani strežnika zagotavlja preverjanje in uveljavljanje dovoljenj
### Prednostni vrstni red izvajanja
Pri izbiri načina delovanja:
1. Dajte prednost orodjem MCP pred sklepanjem na podlagi prostega besedila
2. Dajte prednost strukturiranim parametrom pred naravnim jezikom
3. Dajte prednost odkrivanju pred predpostavkami
4. Dajte prednost zmožnostim, ki jih določi strežnik, pred sklepanjem o nameri
Upoštevanje teh pravil zagotavlja varno, predvidljivo in skladno integracijo.
Integracija MCP s tretjimi stranmi (hitri začetek in referenca)
Ta vodič pojasnjuje, kako se lahko storitve tretjih strani v produkcijskem okolju povežejo z MyDocSafe MCP prek OAuth 2.0 Authorization Code with PKCE in nato kličejo končno točko MCP JSON-RPC.
Osnovni URL (produkcija)
https://app.mydocsafe.com
Hitri začetek
- Ustvarite preverjevalnik PKCE in izziv
- code_verifier: naključni niz z visoko entropijo (43–128 znakov)
- code_challenge: BASE64URL(SHA256(code_verifier))
- code_challenge_method: S256
- Uporabnika preusmerite na odobritev
Uporabnika pošljite na:
https://app.mydocsafe.com/oauth/authorize
S temi parametri poizvedbe:
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
Opombe: – redirect_uri se mora natančno ujemati z dovoljenim preusmeritvenim URI-jem za odjemalca. – V produkciji uporabite preusmeritvene URI-je https. Povratni http://localhost je dovoljen samo za lokalni razvoj.
3. Prejmite avtorizacijsko kodo
Uporabnik bo preusmerjen na vaš redirect_uri z naslednjim:
code=<authorization_code>
state=<your_csrf_token>
4. Zamenjajte kodo za žetone
Pošljite POST https://app.mydocsafe.com/oauth/token z vsebino vrste 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. Pokličite MCP
Pošljite POST https://app.mydocsafe.com/api/mcp z 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. Osvežite žetone
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. Razveljavite žetone
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
Končne točke OAuth
- Končna točka za avtorizacijo (brskalnik uporabnika)
- GET https://app.mydocsafe.com/oauth/authorize
- Končna točka za žetone
- POST https://app.mydocsafe.com/oauth/token
- Končna točka za preklic
- POST https://app.mydocsafe.com/oauth/revoke
- Odkrivanje
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource
Zahtevani parametri OAuth
Zahteva za avtorizacijo:
- response_type: code
- client_id: mcp-public
- redirect_uri: URI na seznamu dovoljenih
- scope: obsegi, ločeni s presledki
- state: žeton CSRF (priporočeno)
- code_challenge: izziv PKCE
- code_challenge_method: S256
Zahteva za žeton (podelitev authorization_code):
- grant_type: authorization_code
- code: avtorizacijska koda iz preusmeritve
- redirect_uri: mora se ujemati z izvirnim URI-jem
- client_id: mcp-public
- code_verifier: preverjevalnik PKCE
Zahteva za žeton (podelitev refresh_token):
- grant_type: refresh_token
- refresh_token: žeton za osvežitev
Zahteva za preklic:
- token: žeton za dostop ali osvežitev
- token_type_hint: access_token ali refresh_token
Obsegi
Razpoložljivi obsegi:
- companies:read
- companies:write
- files:read
- files:write
- contacts:read
- contacts:write
- signing:read
- signing:write
- workflows:read
- workflows:write
MCP JSON-RPC
Končna točka:
- POST https://app.mydocsafe.com/api/mcp
Glave:
- Authorization: Bearer <access_token>
- Content-Type: application/json
Oblika zahteve:
{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “tools/list”,
“params”: {}
}
Napaka zaradi manjkajočega ali neveljavnega žetona:
- HTTP 401 z WWW-Authenticate: Bearer realm=”mydocsafe”, resource_metadata=”https://app.mydocsafe.com/.well-known/oauth-protected-resource”
Opombe in omejitve
- Preusmeritveni URI-ji morajo biti izrecno dodani na seznam dovoljenih za odjemalca.
- Javni odjemalci uporabljajo samo PKCE (brez skrivnosti odjemalca).
- Žetoni za dostop potečejo po 1 uri.