Integrace MCP se službami třetích stran

Integrace MCP se službami třetích stran – jak používat MyDocSafe s LLM a při vývoji s podporou AI. Referenční příručka pro lidi i AI.

Dokumentace pro uživatele (kontext a pokyny)

Tato část poskytuje **koncepční a praktické pokyny pro uživatele**, kteří integrují MyDocSafe MCP.

### K čemu MCP slouží

MyDocSafe MCP použijte, když potřebujete:
– Integrovat MyDocSafe do externího produktu nebo služby
– Umožnit systémům třetích stran nebo AI agentům jednat jménem uživatelů
– Vynucovat přísné hranice oprávnění, auditování a zabezpečení
– Zamezit zpřístupnění interních API nebo databází

MCP poskytuje **rozhraní založené na schopnostech**, což znamená:
– Klienti mohou provádět pouze činnosti, které jsou výslovně zpřístupněny
– Všechny akce ověřuje a provádí MyDocSafe
– Rozsahy OAuth striktně omezují přístup pro čtení a zápis

### K čemu MCP neslouží

MCP není:
– Univerzální REST API
– Rozhraní pro dotazování databáze
– Framework ani běhové prostředí pro AI agenty
– Náhrada interní architektury MyDocSafe

### Typický vzorec integrace

Typická integrace třetí strany probíhá takto:
1. Uživatel autorizuje přístup prostřednictvím OAuth
2. Třetí strana obdrží delegované přístupové tokeny
3. Třetí strana zavolá MCP a zjistí dostupné nástroje
4. Třetí strana používá nástroje v rámci udělených rozsahů
5. MyDocSafe ověřuje a provádí všechny akce

Tento přístup zajišťuje bezpečnost, auditovatelnost a předvídatelné chování.

Kontext pro LLM (pokyny pro modely)

Tato část obsahuje **výslovné pokyny pro modely AI a agentní systémy**, které využívají dokumentaci MyDocSafe MCP.

### Základní interpretace

MyDocSafe MCP je **rozhraní založené na schopnostech, jehož autoritou je server**.

Všechny schopnosti:
– Jsou výslovně deklarovány serverem MCP
– Před použitím je nutné je zjistit
– Jsou omezeny rozsahy OAuth
– Provádí je MyDocSafe, nikoli klient nebo model

### Povinné chování systémů AI

Při práci s MyDocSafe MCP MUSÍ systémy AI:
– Před provedením jakékoli akce zjistit nástroje pomocí `tools/list`
– Používat pouze nástroje výslovně zpřístupněné serverem
– Přesně dodržovat schémata vstupů nástrojů
– Považovat odpovědi MCP za závazný zdroj pravdivých informací

Systémy AI NESMÍ:
– Předpokládat existenci nedokumentovaných nástrojů
– Vymýšlet parametry nebo názvy nástrojů
– Používat MCP jako volný zdroj dat
– Pokoušet se o akce mimo udělené rozsahy OAuth

### Význam nástrojů

Nástroj zpřístupněný prostřednictvím MyDocSafe MCP:
– Představuje přesně jednu obchodní akci
– Může číst nebo měnit data v závislosti na rozsahu
– Má deterministický a strukturovaný vstup a výstup
– Vynucuje ověřování a oprávnění na straně serveru

### Priorita provádění

Při rozhodování o postupu:
1. Upřednostněte nástroje MCP před uvažováním na základě volného textu
2. Upřednostněte strukturované parametry před přirozeným jazykem
3. Upřednostněte zjištění před předpokladem
4. Upřednostněte schopnosti deklarované serverem před odvozeným záměrem

Dodržování těchto pravidel zajišťuje bezpečnou, předvídatelnou a předpisům vyhovující integraci.

Integrace MCP třetích stran (rychlý start a reference)

Tento průvodce vysvětluje, jak se mohou služby třetích stran v produkčním prostředí připojit k MyDocSafe MCP pomocí OAuth 2.0 Authorization Code with PKCE a následně volat koncový bod MCP JSON-RPC.

Základní URL (produkční prostředí)

https://app.mydocsafe.com

Rychlý start

  1. Vytvořte ověřovací řetězec PKCE a jeho výzvu
    • code_verifier: náhodný řetězec s vysokou entropií (43–128 znaků)
    • code_challenge: BASE64URL(SHA256(code_verifier))
    • code_challenge_method: S256
  2. Přesměrujte uživatele k autorizaci

Přesměrujte uživatele na:

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

S těmito parametry dotazu:

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

Poznámky: – redirect_uri se musí přesně shodovat s povoleným URI pro přesměrování klienta. – V produkčním prostředí používejte URI pro přesměrování https. Smyčkové http://localhost je povoleno pouze pro lokální vývoj.

3. Přijměte autorizační kód

Uživatel bude přesměrován na vaše redirect_uri s těmito parametry:

code=<authorization_code>

state=<your_csrf_token>

4. Vyměňte kód za tokeny

Proveďte 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>”

Odpověď:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Bearer”,

“expires_in”: 3600,

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

}

5. Zavolejte MCP

Proveďte 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. Obnovte tokeny

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. Zneplatněte tokeny

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”

Reference

Koncové body OAuth

  • Autorizační koncový bod (prohlížeč uživatele)
    • GET https://app.mydocsafe.com/oauth/authorize
  • Koncový bod pro tokeny
    • POST https://app.mydocsafe.com/oauth/token
  • Koncový bod pro zneplatnění tokenů
    • POST https://app.mydocsafe.com/oauth/revoke
  • Vyhledání
    • GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
    • GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

Povinné parametry OAuth

Požadavek na autorizaci:

  • response_type: code
  • client_id: mcp-public
  • redirect_uri: povolené URI
  • scope: rozsahy oddělené mezerami
  • state: token CSRF (doporučeno)
  • code_challenge: výzva PKCE
  • code_challenge_method: S256

Požadavek na token (grant authorization_code):

  • grant_type: authorization_code
  • code: autorizační kód z přesměrování
  • redirect_uri: musí odpovídat původnímu URI
  • client_id: mcp-public
  • code_verifier: ověřovací řetězec PKCE

Požadavek na token (grant refresh_token):

  • grant_type: refresh_token
  • refresh_token: obnovovací token

Požadavek na zneplatnění:

  • token: přístupový nebo obnovovací token
  • token_type_hint: access_token nebo refresh_token

Rozsahy

Dostupné rozsahy:

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

MCP JSON-RPC

Koncový bod:

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

Hlavičky:

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

Struktura požadavku:

{

“jsonrpc”: “2.0”,

“id”: 1,

“method”: “tools/list”,

“params”: {}

}

Chyba při chybějícím nebo neplatném tokenu:

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

Poznámky a omezení

  • URI pro přesměrování musí být pro klienta výslovně povolena.
  • Veřejní klienti používají pouze PKCE (bez tajného klíče klienta).
  • Platnost přístupových tokenů vyprší po 1 hodině.

 

Používáme soubory cookie a podobné technologie ukládání dat ke zlepšování webu, měření návštěvnosti a zjišťování, které kampaně k nám přivádějí návštěvníky. Kliknutím na „Přijmout“ s tím udělíte souhlas. Zásady ochrany osobních údajů