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