Inizia con un esempio funzionante
Avvia l’esempio e personalizzalo
Crea l’API Orders, un database PostgreSQL e il server MCP che preferisci in Adios. Carichiamo il codice, configuriamo credenziali JWT separate e avviamo le anteprime di sviluppo.
Avvia su Adios →Non hai ancora un account? Creane uno e torna a questo esempio. Scegli un team e controlla le risorse prima di avviare. L’esempio completo richiede un piano a pagamento con spazio per due workspace e un database.
Costruiscilo passo dopo passo
Segui la guida manuale
Progetta l’API e lo schema, aggiungi l’autenticazione JWT, scrivi gli strumenti MCP ed eseguili nei tuoi workspace di sviluppo. Ogni passaggio include codice e comandi.
Segui i passaggi manuali →Esplora prima l’esempio in esecuzione. OAuth per l’accesso degli utenti e il deployment in produzione vengono dopo.
Progetta l’API per un caso d’uso reale
Parti dallo scopo dell’API. L’esempio consente a una dashboard interna, un assistente di supporto e un’automazione di consultare lo stato di spedizione di un ordine. Tutti usano la stessa operazione di business. L’API gestisce dati e regole di accesso; MCP permette al client IA di scoprire e chiamare l’operazione.
Definisci la prima versione in sola lettura: un chiamante autorizzato fornisce un ID ordine e riceve ID e stato di spedizione. Escludi indirizzi, dati di pagamento e note interne. Creare ordini, emettere rimborsi e modificare spedizioni richiede endpoint e permessi separati.
- Chi chiama l’API? Un utente o servizio noto con un tenant assegnato.
- Cosa può fare? Leggere gli ordini del tenant con il permesso orders:read.
- Qual è il compito dell’API? Validare la richiesta, verificare il chiamante, applicare le regole di proprietà e restituire una risposta stabile.
- Qual è il compito di MCP? Descrivere uno strumento specifico, validare l’input e chiamare l’API con l’identità verificata del chiamante.
Scrivi il contratto prima di scegliere un SDK. Mantiene sito, integrazioni e strumenti IA sullo stesso modello di permessi, senza dare al client IA accesso diretto al database.
Progetta lo schema e le regole di proprietà
Usa PostgreSQL nell’esempio. Un tenant rappresenta un negozio o un’organizzazione. Un’identità collega il subject di un token verificato a un tenant e può essere disattivata. Un ordine appartiene a un tenant. L’API usa questa relazione per autorizzarne la lettura.
| Tabella | Obiettivo | Regola di accesso |
|---|---|---|
tenants | Essere proprietario dei dati dell’organizzazione | Referenziato da identità e ordini |
principals | Associare un subject verificato a un tenant | Solo le identità attive possono leggere i dati |
orders | Memorizzare lo stato di spedizione | Il tenant del chiamante deve coincidere con quello dell’ordine |
-- Demo bootstrap only. Use versioned migrations for an existing production DB.
CREATE TABLE IF NOT EXISTS tenants (
id uuid PRIMARY KEY,
name text NOT NULL
);
CREATE TABLE IF NOT EXISTS principals (
subject text PRIMARY KEY,
tenant_id uuid NOT NULL REFERENCES tenants(id),
active boolean NOT NULL DEFAULT true
);
CREATE TABLE IF NOT EXISTS orders (
tenant_id uuid NOT NULL REFERENCES tenants(id),
id varchar(64) NOT NULL CHECK (id ~ '^[A-Za-z0-9-]{1,64}$'),
status text NOT NULL CHECK (status IN ('pending', 'shipped', 'delivered')),
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, id)
);
-- Fictional data; ownership comes from the verified subject, not tool input.
INSERT INTO tenants (id, name) VALUES
('11111111-1111-4111-8111-111111111111', 'Demo shop'),
('22222222-2222-4222-8222-222222222222', 'Other shop')
ON CONFLICT DO NOTHING;
INSERT INTO principals (subject, tenant_id) VALUES
('demo-client', '11111111-1111-4111-8111-111111111111'),
('other-client', '22222222-2222-4222-8222-222222222222')
ON CONFLICT DO NOTHING;
INSERT INTO orders (tenant_id, id, status) VALUES
('11111111-1111-4111-8111-111111111111', 'demo-1001', 'shipped'),
('22222222-2222-4222-8222-222222222222', 'other-1002', 'pending')
ON CONFLICT DO NOTHING;La chiave composta permette lo stesso ID ordine in tenant diversi. Le chiavi esterne impediscono record orfani e il vincolo di stato esclude valori non supportati. La query collega il subject verificato al tenant e all’ordine; il chiamante non sceglie un tenant nell’input dello strumento.
L’inizializzazione include due tenant fittizi per testare l’isolamento: demo-client può leggere demo-1001, mentre other-client possiede other-1002. La demo esegue un bootstrap idempotente all’avvio. Per un database di produzione esistente, usa migrazioni versionate e separa il provisioning dalle richieste dell’applicazione.
Definisci endpoint, risposte e autenticazione JWT
L’API pubblica espone un endpoint di ricerca ordini. Una risposta riuscita è un piccolo oggetto JSON con id e status. Mantieni stabile lo schema per il sito e lo strumento MCP.
GET /orders/demo-1001
Authorization: Bearer <API-audience JWT>
200 { "id": "demo-1001", "status": "shipped" }
401 missing, invalid or expired JWT
403 valid JWT without orders:read
404 unknown order, inactive identity or another tenant’s order
503 database unavailableL’autenticazione JWT è il minimo in tutte le implementazioni seguenti. L’header bearer trasporta il token; non basta confrontarlo con una stringa casuale o solo decodificarlo. Verifica la firma con un algoritmo consentito, richiedi emittente e audience previsti, controlla scadenza e subject e applica lo scope prima di accedere al database.
{
"iss": "orders-demo",
"aud": "orders-mcp",
"sub": "demo-client",
"scope": "orders:read",
"iat": 1791498000,
"exp": 1791498900
}La demo controllata usa HS256 con segreti di firma separati per API e MCP. Uno script riservato all’operatore emette un JWT MCP breve. Il server lo verifica e firma un nuovo JWT di cinque minuti per l’audience orders-api con lo stesso subject verificato. L’API verifica il secondo token e cerca il tenant del subject in PostgreSQL.
MCP diventa un gateway fidato autorizzato a firmare token API. Non distribuire segreti di firma ai client né esporre l’emittente come endpoint pubblico. Fuori da questo ambito di fiducia, preferisci un provider OAuth con JWT asimmetrici e verifica le sue chiavi pubbliche; la sezione OAuth mostra il resource server. JWT è un formato di token; OAuth gestisce autorizzazione delegata e flussi di accesso.
Non accettare un ID tenant del client come prova di proprietà. Non inoltrare un token con audience MCP all’API. Usa token brevi, ruota le chiavi e usa HTTPS in produzione. Con più provider di identità, associa emittente e subject a un’identità canonica invece di presumere che i subject siano globalmente univoci.
Emittente JWT di demo riservato all’operatore
import { createHmac } from "node:crypto";
// Operator-only demo issuer. Never expose this script or its key to end users.
const audience = process.argv[2] || "orders-mcp";
if (!["orders-mcp", "orders-api"].includes(audience))
throw new Error("Unknown audience");
const secret =
process.env[audience === "orders-api" ? "API_JWT_SECRET" : "MCP_JWT_SECRET"];
if (!secret || secret.length < 32)
throw new Error("Set the audience's JWT signing secret");
const encode = (value) =>
Buffer.from(JSON.stringify(value)).toString("base64url");
const now = Math.floor(Date.now() / 1000);
const data = `${encode({ alg: "HS256", typ: "JWT" })}.${encode({ iss: "orders-demo", aud: audience, sub: "demo-client", scope: "orders:read", iat: now, exp: now + 900 })}`;
process.stdout.write(
`${data}.${createHmac("sha256", secret).update(data).digest("base64url")}`,
);Implementa l’API prima di aggiungere MCP
Decomprimi gli esempi e apri api/. L’implementazione Node.js usa jose per verificare JWT e pg per interrogare PostgreSQL. Installa le dipendenze bloccate con npm ci. La query parametrizzata collega il subject verificato al tenant e restituisce solo gli ordini di quel tenant.
Dipendenze API e comando di avvio
{
"name": "orders-api",
"private": true,
"type": "module",
"scripts": {
"start": "node init-db.mjs && node server.mjs"
},
"dependencies": {
"jose": "^6.1.0",
"pg": "8.23.1"
}
}import http from "node:http";
import { jwtVerify } from "jose";
import pg from "pg";
const secret = process.env.API_JWT_SECRET;
if (!secret || secret.length < 32 || !process.env.DATABASE_URL) {
throw new Error(
"Set DATABASE_URL and an API_JWT_SECRET of at least 32 characters",
);
}
const key = new TextEncoder().encode(secret);
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 5,
connectionTimeoutMillis: 5000,
statement_timeout: 5000,
});
pool.on("error", () => console.error("Database connection failed"));
await pool.query("SELECT 1");
const server = http.createServer(async (req, res) => {
const send = (status, data) => {
res.writeHead(status, {
"Content-Type": "application/json",
"Cache-Control": "no-store",
});
res.end(JSON.stringify(data));
};
if (req.url === "/healthz" && req.method === "GET") {
try {
await pool.query("SELECT 1");
return send(200, { ok: true });
} catch {
return send(503, { ok: false });
}
}
let principal;
try {
const match = /^Bearer (\S+)$/.exec(req.headers[(process.env.API_AUTH_HEADER || "Authorization").toLowerCase()] || "");
if (!match) throw new Error("Missing access token");
const { payload } = await jwtVerify(match[1], key, {
issuer: "orders-demo",
audience: "orders-api",
algorithms: ["HS256"],
requiredClaims: ["sub", "exp"],
});
if (typeof payload.sub !== "string" || !payload.sub)
throw new Error("Missing subject");
if (
typeof payload.scope !== "string" ||
!payload.scope.split(" ").includes("orders:read")
) {
return send(403, { error: "orders:read permission required" });
}
principal = payload.sub;
} catch {
res.setHeader("WWW-Authenticate", 'Bearer error="invalid_token"');
return send(401, { error: "Invalid or expired access token" });
}
const match = /^\/orders\/([a-zA-Z0-9-]{1,64})$/.exec(req.url || "");
if (req.method !== "GET" || !match) return send(404, { error: "Not found" });
try {
const result = await pool.query(
`SELECT o.id, o.status FROM orders o
JOIN principals p ON p.tenant_id = o.tenant_id
WHERE p.subject = $1 AND p.active = true AND o.id = $2`,
[principal, match[1]],
);
// The same 404 covers unknown IDs and orders outside the caller's tenant.
return result.rows[0]
? send(200, result.rows[0])
: send(404, { error: "Order not found" });
} catch {
return send(503, { error: "Order service unavailable" });
}
});
server.requestTimeout = 10_000;
server.listen(
Number(process.env.PORT || 8081),
process.env.HOST || "127.0.0.1",
);Inizializza il database di demo
import { readFile } from "node:fs/promises";
import pg from "pg";
if (!process.env.DATABASE_URL) throw new Error("Set DATABASE_URL");
const deadline = Date.now() + 45_000;
let client;
while (true) {
client = new pg.Client({
connectionString: process.env.DATABASE_URL,
connectionTimeoutMillis: 5000,
statement_timeout: 10000,
});
try {
await client.connect();
break;
} catch {
await client.end().catch(() => {});
if (Date.now() >= deadline)
throw new Error(
"Database unavailable. Check its private endpoint and credentials.",
);
await new Promise((resolve) => setTimeout(resolve, 1000));
}
}
try {
await client.query(
await readFile(new URL("./schema.sql", import.meta.url), "utf8"),
);
console.log("Demo database initialized");
} catch {
throw new Error("Could not initialize the demo database");
} finally {
await client.end();
}L’API restituisce lo stesso 404 per ordini assenti e inaccessibili, evitando di rivelare gli ID di altri tenant. La rotta pubblica di integrità verifica la connessione al database senza esporre dati o richiedere JWT.
Se hai già un’API, mantieni modello e controlli di proprietà. Adatta endpoint e mappatura della risposta nell’handler MCP. Usa un’origine e un endpoint fissi invece di accettare URL arbitrari dall’input dello strumento.
Aggiungi MCP come livello di strumenti sopra l’API
Model Context Protocol (MCP) offre ai client IA un modo standard per scoprire e chiamare strumenti. Il server descrive uno strumento, accetta input validati, esegue l’operazione e restituisce un risultato. La tua API REST può continuare a servire il sito e le altre integrazioni.
AI client → HTTPS /mcp → get_order({ order_id: "demo-1001" })
→ GET /orders/demo-1001 → { id: "demo-1001", status: "shipped" }
Client → MCP: MCP_ACCESS_TOKEN, or a user OAuth access token
MCP → API: newly signed API JWT with the verified caller’s subjectIl server verifica il JWT client prima di creare l’handler. Ogni chiamata API usa un nuovo JWT con un’altra audience e il subject verificato. L’API continua ad applicare le regole di proprietà del database; MCP non le aggira.
Usa Streamable HTTP per un server remoto. Stdio è utile quando un client desktop avvia un processo locale. Questi esempi HTTP sono stateless e restituiscono JSON; non richiedono archiviazione di sessioni né un flusso di eventi persistente. Espongono /mcp per il protocollo e un endpoint pubblico /healthz per la sonda del runtime.
Servono PostgreSQL e Node.js 24 per l’API, oltre a Node.js 24, Python 3.13 o Go 1.25 per il server MCP scelto. Installa la CLI Adios e prepara un team Adios. Gli esempi usano gli SDK ufficiali JavaScript 1.32.1, Python 1.30.0 e Go 1.8.0; evita di combinarli con tutorial di altre versioni principali.
Scegli una guida per linguaggio
Il contratto dell’API e il modello dei permessi restano uguali. Continua con il linguaggio che usi: ogni guida contiene il proprio codice server, le dipendenze, i controlli del workspace e il manifesto di distribuzione Adios.
JavaScript
Usa l’SDK JavaScript, schemi degli strumenti Zod ed Express. Include l’esempio facoltativo di server di risorse OAuth.
Aprire la guida JavaScriptPython 3.13Python
Usa FastMCP, strumenti tipizzati, HTTPX e un controllo JWT ASGI. Trova la configurazione e la distribuzione Python in un’unica guida.
Aprire la guida PythonGo 1.25Go
Usa l’SDK Go, struct tipizzate di input e output e middleware HTTP. Compila e distribuisci un unico binario del servizio.
Aprire la guida GoLe tre implementazioni chiamano l’API condivisa e verificano i JWT. La guida JavaScript include anche il controllo OAuth facoltativo del server di risorse; Python e Go descrivono l’autorizzazione necessaria prima di consentire l’accesso degli utenti.
Sviluppare in un workspace Adios
Usa un team di sviluppo Adios e PostgreSQL gestito. Il tuo computer carica solo il codice ed esegue il test del client; i processi API e MCP girano nei workspace Adios.
adios login
adios teams
adios teams switch YOUR_DEV_TEAM_ID
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdin
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
adios databases create orders-dev-db --template postgres:16 \
--region de --database orders --user orders_api \
--password-secret ORDERS_DB_PASSWORDAttendi che il database sia pronto. Copia il suo URL di connessione dai dettagli nella Console e salvalo come ORDERS_DEV_DATABASE_URL tramite l’inserimento del segreto. Usa l’host assegnato e verifica che la regione del workspace possa raggiungerlo.
adios secrets set ORDERS_DEV_DATABASE_URL --stdin
# Paste the database connection URL, then finish stdin with Ctrl-D.
cp api/adios.dev.yaml api/adios.yaml
adios ws create --name orders-api-dev --json
# Copy workspace_id from the response:
export API_WORKSPACE_ID=YOUR_API_WORKSPACE_ID
(cd api && adios sync "$API_WORKSPACE_ID")
adios ws run start "$API_WORKSPACE_ID" --wait --json
adios ws get "$API_WORKSPACE_ID"Crea prima un workspace indipendente, poi sincronizza il codice. Creare un workspace dal percorso di un progetto può richiedere un’applicazione già distribuita; questo flusso indipendente permette di iniziare lo sviluppo senza pubblicare una versione.
name: orders-api-dev
region: de
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
env:
API_AUTH_HEADER: X-Orders-Token
HOST: 0.0.0.0
PORT: "8081"
DATABASE_URL: secret://ORDERS_DEV_DATABASE_URL
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRETL’anteprima dell’API inizializza lo schema dimostrativo e avvia il processo Node.js. Copia la sua origine HTTPS effettiva dal risultato di esecuzione o dalla Console. Mantieni aperto questo terminale affinché l’emittente del client conservi le chiavi di firma.
export API_BASE_URL=https://YOUR-API-PREVIEW-HOST
export API_ACCESS_TOKEN="$(node issue-token.mjs orders-api)"
curl --fail "$API_BASE_URL/healthz"
curl --fail -H "Authorization: Bearer $API_ACCESS_TOKEN" \
"$API_BASE_URL/orders/demo-1001"Continua con la guida del tuo linguaggio per creare il workspace MCP. Aggiorna i file con adios sync e riavvia l’anteprima per applicare le modifiche. Un’anteprima è un runtime di sviluppo, non una versione pubblicata dell’applicazione.
Scegliere un’implementazione per linguaggio →Arresta le anteprime dai controlli del workspace quando hai finito. Il database gestito ha un ciclo di vita separato; arrestare un’anteprima non lo arresta né lo elimina.
adios ws run stop "$API_WORKSPACE_ID"Aggiungi OAuth per accesso utente e permessi delegati
Gli esempi JWT coprono un’integrazione controllata con token emessi dall’operatore. Non implementano accesso utente, consenso o rinnovo. Aggiungi OAuth per account personali o client che richiedono il flusso MCP. La modalità OAuth dell’esempio accetta JWT di accesso emessi dal provider.
Il server MCP è la risorsa protetta. Un server di autorizzazione gestisce accesso, consenso ed emissione dei token. Il tuo provider OAuth può farlo se supporta la discovery e la registrazione necessarie ai client MCP. Adios ospita l’applicazione e conserva i segreti; l’accesso alla CLI non aggiunge OAuth automaticamente all’app.
- Pubblica i metadati della risorsa in
/.well-known/oauth-protected-resource/mcp, indicando URL MCP, server di autorizzazione e scope supportati. - Restituisci 401 per una richiesta non autenticata con un header
WWW-Authenticateche punti a quei metadati. - Il client scopre i metadati OAuth o OpenID Connect del server di autorizzazione. Organizza preregistrazione, documenti di metadati client o registrazione dinamica secondo il supporto di provider e client.
- L’utente accede e concede l’autorizzazione. Il client usa un flusso di codice di autorizzazione con PKCE e richiede un token per la risorsa MCP.
- Valida la firma o il risultato di introspezione del token, l’emittente, l’audience, la scadenza e gli scope. Associa il subject all’utente e al tenant prima di eseguire uno strumento.
Inizia con orders:read. Proteggi gli strumenti di scrittura con permessi separati e conferma esplicita se il client la supporta. Un token di identità non è un token di accesso API e un accesso valido non autorizza a leggere gli ordini di tutti i clienti.
La guida JavaScript include un controllo facoltativo completo del server di risorse con JWT RS256. Pubblica i metadati della risorsa e verifica i token del provider, ma non implementa accesso, consenso, registrazione dei client o emissione dei token.
Seguire l’implementazione OAuth in JavaScript →Python e Go richiedono un verificatore equivalente dei token del provider e metadati della risorsa prima di accettare token OAuth degli utenti. Il solo valore di un token non abilita OAuth nelle demo JWT.
Un’API di terze parti può richiedere una connessione OAuth separata. Conserva i refresh token in modo sicuro, associali all’utente corretto e richiedi solo i permessi necessari. I client secret del provider vanno nei segreti Adios; gli URL di emittente e JWKS pubblico sono configurazione ordinaria.
Riferimento del protocollo: Specifica di autorizzazione MCP.
Distribuisci PostgreSQL, API e MCP su Adios
Distribuisci due applicazioni: orders-api e orders-mcp. Possono essere rilasciate indipendentemente. Usa lo stesso team Adios per i riferimenti ai segreti. La regione dell’esempio è de; scegli una regione disponibile adatta ai tuoi utenti.
Accedi e crea i segreti
Scegli il team di pubblicazione e genera nuovi segreti di firma e una password del database. Mantieni dati e credenziali separati da quelli di sviluppo. Adios login autentica la CLI sulla piattaforma.
adios login
adios teams
adios teams switch YOUR_RELEASE_TEAM_ID
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdinDistribuisci prima l’API
Il manifesto API dichiara una risorsa Postgres gestita. Adios la provisiona e inserisce DATABASE_URL nel runtime API. La password è un riferimento a un segreto. Il comando di avvio inizializza lo schema di demo prima dell’API; usa il tuo processo normale di migrazione in produzione.
name: orders-api
region: de
replicas: 1
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
resources:
- name: db
template: postgres:16
database: orders
username: orders_api
password: secret://ORDERS_DB_PASSWORD
env:
HOST: 0.0.0.0
PORT: "8081"
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
# Adios injects DATABASE_URL for the managed Postgres resource.(cd api && cp adios.release.yaml adios.yaml && adios up)
adios apps get orders-apiadios up compila, distribuisce e promuove una versione sana. È un comando di distribuzione, non un’anteprima locale. Copia la rotta HTTPS effettiva dall’output o dalla Console e verifica che il suo /healthz restituisca 200.
Collega MCP all’API distribuita
Modifica il manifesto nella directory del linguaggio scelto. Sostituisci https://api.example.com con l’origine effettiva dell’API. Sostituisci https://mcp.example.com con l’origine pubblica del servizio MCP. Sono valori di esempio, non domini forniti da Adios.
env:
HOST: 0.0.0.0
PORT: "8080"
API_BASE_URL: https://YOUR-API-HOST
PUBLIC_ORIGIN: https://YOUR-MCP-HOST
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
MCP_JWT_SECRET: secret://ORDERS_MCP_JWT_SECRETSe non conosci ancora l’hostname MCP predefinito, distribuisci una volta per ottenerlo, aggiorna PUBLIC_ORIGIN e ridistribuisci prima di collegare un client. Le sonde di integrità funzionano durante la configurazione; MCP accetta solo l’origine impostata. Puoi anche verificare un dominio personalizzato e aggiungere custom_hosts prima del rilascio finale.
custom_hosts:
- mcp.example.comI manifesti MCP ascoltano su 0.0.0.0, espongono la porta 8080 e usano /healthz per i controlli di integrità. Adios instrada HTTPS all’applicazione. Mantieni la sonda indipendente dall’autenticazione JWT MCP.
Esegui il comando di distribuzione dalla directory dell’implementazione scelta. La relativa guida contiene il comando e il manifesto esatti.
Aprire i passaggi di distribuzione del tuo linguaggio →Esegui il controllo client sull’URL ospitato:
export MCP_ACCESS_TOKEN="$(node issue-token.mjs)"
export MCP_URL=https://YOUR-MCP-HOST/mcp
.client-venv/bin/python check.pyLa guida usa una rotta API HTTPS con un JWT di audience API. Se sposti l’API su una rete privata, usa l’host assegnato da Adios e verifica la connettività dal runtime MCP. Non dedurre un host interno dal nome dell’applicazione. Consulta il riferimento del manifest per le opzioni di runtime, segreti e instradamento.
Usa gli strumenti ospitati da un client IA
In un client compatibile con Streamable HTTP remoto, aggiungi https://YOUR-MCP-HOST/mcp come URL del server. Per gli esempi privati, configura un header Authorization: Bearer … tramite il meccanismo di segreti o variabili d’ambiente del client. Non incollare credenziali in file di configurazione condivisi.
Per OAuth, aggiungi lo stesso URL e completa l’accesso del client. Deve scoprire i metadati, aprire l’accesso del provider e ricevere un token. Verifica il supporto al flusso di registrazione del provider prima di distribuire l’integrazione.
Verifica che get_order compaia nell’elenco degli strumenti. Chiedi: «Usa il server Orders MCP per controllare lo stato di spedizione dell’ordine demo-1001». Il client può chiamare lo strumento e rispondere che l’ordine è stato spedito. Verifica la chiamata effettiva, non solo una risposta generata dal contesto della chat.
check.py mostra inizializzazione e invocazione tramite script. Con OAuth può accettare un token di accesso valido in MCP_ACCESS_TOKEN, ma non esegue accesso o rinnovo dei token; usa un client compatibile OAuth per questo.
Per consentire a un client IA di aiutarti a distribuire il progetto, collegalo ad Adios MCP. La connessione alla piattaforma e il server Orders MCP ospitato sono integrazioni distinte con permessi separati.
Verifica il servizio prima di condividerlo
La rotta di integrità API verifica PostgreSQL; quella di MCP verifica il processo. Nessuna dimostra che tutti i permessi JWT o OAuth siano corretti. Dopo ogni rilascio, testa inizializzazione, discovery e una chiamata consentita nota.
- Connessione non riuscita: controlla la rotta, TLS,
/mcpePUBLIC_ORIGIN. Il proxy deve preservare l’host previsto e supportare il trasporto scelto. - 401 o 403: controlla le credenziali. Per OAuth, verifica emittente, audience, scadenza, scope e metadati. Prova token scaduti e con audience errata oltre a uno valido.
- Errore dello strumento: controlla URL API, permessi di accesso, timeout e formato della risposta. Non inserire token o risposte private nei log.
- Utenti reali: aggiungi controlli su tenant e risorse, limiti di richieste, rotazione delle credenziali e audit associato al chiamante. Verifica che un utente non possa leggere gli ordini di un altro.
- Più repliche: questi esempi non hanno stato di sessione. Se aggiungi sessioni, notifiche o flussi persistenti, pianifica stato condiviso e instradamento.
adios logs orders-api --runtime
adios logs orders-mcp --runtime
adios logs orders-mcp --buildFissa le versioni delle dipendenze e ripeti il controllo client dopo aver modificato rotte o autenticazione. Definisci permessi e conferme prima di aggiungere strumenti di scrittura.
Domande frequenti
Serve OAuth per ospitare un server MCP?
Un’integrazione controllata può usare un JWT verificato di breve durata se il client supporta header di autorizzazione. Per accesso utente, permessi delegati o client che richiedono il flusso MCP, implementa OAuth. L’accesso alla CLI Adios non autentica gli utenti del tuo server MCP.
Un server MCP può usare la mia API esistente?
Sì. Definisci strumenti con schemi di input, valida ogni richiesta, chiama la tua API con una credenziale destinata a essa e restituisci risultati strutturati. Verifica i permessi del chiamante sul tenant e sulle risorse prima di accedere ai dati reali.
Posso ospitare server MCP JavaScript, Python e Go su Adios?
Sì. Le guide collegate JavaScript, Python e Go includono ciascuna un server Streamable HTTP completo, file delle dipendenze, endpoint di stato e un manifesto adios.yaml. Scegline una e distribuiscila insieme all’API REST condivisa.
Qual è la differenza rispetto ad Adios MCP?
Questa guida crea il tuo servizio MCP. Adios MCP permette a un client IA di gestire workspace e distribuzioni Adios. Puoi usare questa connessione alla piattaforma per creare e distribuire il progetto.