Integrazione di terze parti MCP

Documenti umani (contesto e guida)

Questa sezione fornisce **una guida concettuale e pratica per i lettori umani** che si integra con MyDocSafe MCP.

### A cosa serve MCP

Utilizza MyDocSafe MCP quando hai bisogno di:
– Integrare MyDocSafe in un prodotto o servizio esterno
– Consentire a sistemi di terze parti o agenti di intelligenza artificiale di agire per conto degli utenti
– Applicare rigidi limiti di autorizzazione, controllo e sicurezza
– Evitare di esporre database o dati interni non elaborati

MCP fornisce un'**interfaccia basata sulle capacità**, ovvero:
– I client possono fare solo ciò che è esplicitamente esposto
– Tutte le azioni sono convalidate ed eseguite da MyDocSafe
– Gli ambiti OAuth limitano rigorosamente l'accesso in lettura e scrittura

### Cosa non è MCP

MCP non è:
– Un REST generico API
– Un'interfaccia di query del database
– Un framework o runtime di un agente AI
– Una sostituzione per l'architettura interna di MyDocSafe

### Modello di integrazione tipico

Una tipica integrazione di terze parti segue questo schema:
1. L'utente autorizza l'accesso tramite OAuth
2. La terza parte riceve token di accesso delegati
3. La terza parte chiama MCP per scoprire gli strumenti disponibili
4. La terza parte esegue strumenti entro gli ambiti concessi
5. MyDocSafe convalida ed esegue tutte le azioni

Questo approccio garantisce sicurezza, verificabilità e comportamento prevedibile.

Contesto per gli LLM (orientamento modello)

Questa sezione fornisce **una guida esplicita per i modelli di intelligenza artificiale e i sistemi di agenti** che utilizzano la documentazione MCP MyDocSafe.

### Interpretazione canonica

MyDocSafe MCP è un'**interfaccia basata sulle capacità e con autorità sul server**.

Tutte le funzionalità:
– Sono dichiarati esplicitamente dal server MCP
– Deve essere scoperto prima dell’uso
– Sono vincolati da ambiti OAuth
– Vengono eseguiti da MyDocSafe, non dal client o dal modello

### Comportamento richiesto per i sistemi di intelligenza artificiale

Quando interagiscono con MyDocSafe MCP, i sistemi di intelligenza artificiale DEVONO:
– Scopri gli strumenti utilizzando `tools/list` prima di tentare qualsiasi azione
– Utilizzare solo strumenti esplicitamente esposti dal server
– Abbinare esattamente gli schemi di input degli strumenti
– Trattare le risposte MCP come verità autorevole di base

I sistemi di intelligenza artificiale NON DEVONO:
– Supporre l’esistenza di strumenti non documentati
– Parametri di fabbricazione o nomi di utensili
– Utilizzare MCP come fonte di dati in formato libero
– Tentare azioni al di fuori degli ambiti OAuth concessi

### Semantica degli strumenti

Uno strumento esposto da MyDocSafe MCP:
– Rappresenta esattamente un'azione aziendale
– Può leggere o modificare i dati a seconda dell’ambito
– Ha input e output deterministici e strutturati
– Applica la convalida e le autorizzazioni lato server

### Priorità di esecuzione

Quando si sceglie come agire:
1. Preferire gli strumenti MCP al ragionamento a testo libero
2. Preferire i parametri strutturati al linguaggio naturale
3. Preferire la scoperta all'ipotesi
4. Preferire la capacità dichiarata dal server rispetto all'intento inferito

Il rispetto di queste regole garantisce un'integrazione sicura, prevedibile e conforme.

Integrazione di terze parti MCP (avvio rapido + riferimento)

Questa guida spiega come i servizi di terze parti possono connettersi a MyDocSafe MCP in produzione utilizzando il codice di autorizzazione OAuth 2.0 con PKCE e quindi chiamare l'endpoint JSON-RPC MCP.

URL di base (produzione)

https://app.mydocsafe.com

Avvio rapido

Crea un verificatore PKCE e una sfida
- code_verifier: stringa casuale ad alta entropia (43-128 caratteri)
- code_challenge: BASE64URL(SHA256(code_verifier))
- metodo_sfida_codice: S256
Reindirizzare l'utente per autorizzarlo

Invia l'utente a:

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

Con parametri di query:

response_type=codice

client_id=mcp-public

redirect_uri=<il_tuo_redirect_uri>

ambito=aziende:lettura file:lettura contatti:lettura

stato=<il_tuo_token_csrf>

code_challenge=<pkce_challenge>

metodo_sfida_codice=S256

Note: – redirect_uri deve corrispondere esattamente a un URI di reindirizzamento consentito per il client. – Per la produzione, utilizzare URI di reindirizzamento https. Il loopback http://localhost è consentito solo per lo sviluppo locale.

3. Ricevi il codice di autorizzazione

L'utente viene reindirizzato al tuo redirect_uri con:

codice=<codice_autorizzazione>

stato=<il_tuo_token_csrf>

4. Codice di scambio per i token

POST https://app.mydocsafe.com/oauth/token con 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 “codice=<codice_autorizzazione>” \

-d “redirect_uri=<tuo_redirect_uri>” \

-d “client_id=mcp-public” \

-d “code_verifier=<pkce_verifier>”

Risposta:

{

“access_token”: “….”,

“refresh_token”: “….”,

“token_type”: “Portatore”,

“scade_in”: 3600,

“ambito”: “aziende:leggi file:leggi contatti:leggi”

}

5. Chiama MCP

POST https://app.mydocsafe.com/api/mcp con Autorizzazione: Bearer <access_token>:

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H "Autorizzazione: Portatore <token di accesso>" \

-H "Tipo di contenuto: applicazione/json" \

-D '{

"jsonrpc": "2.0",

“id”: 1,

“metodo”: “strumenti/elenco”,

“parametri”: {}

6. Aggiorna i token

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. Revoca i token

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H "Content-Type: application/x-www-form-urlencoded" \

-d “token=<token_di_accesso_o_aggiornamento>” \

-d “suggerimento_tipo_token=token_accesso”

Riferimento

OAuth endpoint

Endpoint di autorizzazione (browser utente)
- OTTIENI https://app.mydocsafe.com/oauth/authorize
Punto finale del token
- POST https://app.mydocsafe.com/oauth/token
Punto finale di revoca
- POST https://app.mydocsafe.com/oauth/revoke
Scoperta
- OTTIENI https://app.mydocsafe.com/.well-known/oauth-authorization-server
- OTTIENI https://app.mydocsafe.com/.well-known/oauth-protected-resource

Parametri richiesti OAuth

Richiesta di autorizzazione:

response_type: codice
client_id: mcp-public
redirect_uri: URI consentito
ambito: ambiti separati da spazi
stato: token CSRF (consigliato)
code_challenge: sfida PKCE
metodo_sfida_codice: S256

Richiesta token (concessione authorization_code):

grant_type: codice di autorizzazione
codice: codice di autorizzazione dal reindirizzamento
redirect_uri: deve corrispondere all'originale
client_id: mcp-public
code_verifier: verificatore PKCE

Richiesta token (concessione refresh_token):

grant_type: refresh_token
refresh_token: token di aggiornamento

Richiesta di revoca:

token: token di accesso o aggiornamento
token_type_hint: token di accesso o token di aggiornamento

Ambiti di applicazione

Ambiti disponibili:

aziende:leggi
aziende:scrivi
file:letti
file:scrivi
contatti:leggi
contatti:scrivi
firma:letto
firma:scrivi
flussi di lavoro: lettura
flussi di lavoro: scrittura

MCP JSON-RPC

Punto finale:

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

Intestazioni:

Autorizzazione: Portatore <access_token>
Tipo di contenuto: applicazione/json

Forma richiesta:

{

"jsonrpc": "2.0",

“id”: 1,

“metodo”: “strumenti/elenco”,

“parametri”: {}

}

Errore per token mancante/non valido:

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

Note e vincoli

Gli URI di reindirizzamento devono essere esplicitamente consentiti per il client.
I client pubblici utilizzano solo PKCE (nessun segreto client).
I token di accesso scadono tra 1 ora.