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

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

 

Piškotke in podobne tehnologije shranjevanja uporabljamo za izboljšanje spletnega mesta, merjenje obiska in ugotavljanje, katere kampanje privabljajo obiskovalce. Če se s tem strinjate, kliknite »Sprejmi«. Pravilnik o zasebnosti