Démarrage de zéro — ORDS MCP Lab

Prérequis

Ce qu’il faut avoir

Docker Engine + Compose v2
~4–8 Go de RAM (Oracle Free est gourmand)
Un tenant Auth0
OpenCode (opencode --version)
python3 + éventuellement python-jose pour inspecter le jeton

Phase A

Auth0 — à faire entièrement

Compléter la page configuration Auth0, en insistant sur :

API Identifier = http://127.0.0.1:8080/mcp
Permission urn:oracle:dbtools:ords:mcpserver:all sur l’API
Rôles POOL.HR / POOL.FIN avec cette permission sur chaque rôle
App Native + callback http://127.0.0.1:19876/mcp/oauth/callback
Trigger post-login → roles2
Utilisateur avec le bon rôle assigné

Phase B

Fichiers du lab

# depuis le dépôt cloné
cp .env.example .env
# remplir AUTH0_DOMAIN, AUTH0_AUDIENCE, AUTH0_CLIENT_ID
# AUTH0_AUDIENCE=http://127.0.0.1:8080/mcp
# MCP_ROLE_CLAIM=/roles2

cp opencode.json.example opencode.json

Phase C

Démarrer l’infrastructure

docker compose up -d --build
docker compose ps

Attendre que ords et ords-oracle soient healthy. La création du premier volume Oracle exécute sql/01_lab_schemas.sql (HR/FIN + utilisateurs MCP).

Vérifier la base

docker exec -i ords-oracle sqlplus -s sys/${ORACLE_PWD:-OracleFree123}@//localhost/FREEPDB1 as sysdba <<'SQL'
SELECT username FROM dba_users
 WHERE username IN ('HR','FIN','HR_MCP_RO','FIN_MCP_RO')
 ORDER BY 1;
SQL

Vérifier le câblage ORDS MCP + Auth0

curl -sI http://127.0.0.1:8080/mcp | head -10
curl -s http://127.0.0.1:8080/.well-known/oauth-protected-resource/mcp
docker exec ords ords --config /etc/ords/config config list | grep -iE 'audience|issuer|role.claim|feature.mcp'

Phase D

OpenCode OAuth

# le port de callback doit être libre (une seule auth à la fois)
ss -ltnp | grep 19876 || echo "callback port free"

set -a && source .env && set +a
opencode mcp logout ords-mcp 2>/dev/null
opencode mcp auth ords-mcp

Terminer le login navigateur. Puis :

opencode mcp list

Terminé quand :

✓ ords-mcp connected (OAuth)

Comprendre chaque étape de ce login sur la page OAuth pas à pas.

Phase E

Utiliser

opencode

Rôles de l’utilisateur	Prompt	Résultat attendu
`POOL.FIN` seul	« Using ords-mcp, list databases I can access. »	`mcp-fin` seulement
`POOL.FIN`	« On mcp-fin run: select * from invoices »	des lignes
`POOL.FIN`	« On mcp-hr run: select 1 from dual »	refusé / pool absent
`POOL.HR` seul	list databases	`mcp-hr` seulement

Phase F

Scripts de smoke test (optionnel)

# récupérer le token depuis le fichier OpenCode, puis lancer le smoke curl
export MCP_ACCESS_TOKEN=$(python3 - <<'PY'
import json
from pathlib import Path
print(json.loads(Path.home().joinpath(".local/share/opencode/mcp-auth.json").read_text())["ords-mcp"]["tokens"]["accessToken"])
PY
)
./scripts/mcp-curl-smoke.sh

Réinitialisations

Procédures de reset

Objectif	Commande
Redémarrer ORDS seul	`docker compose restart ords`
Reconstruire la config JWT/pools ORDS	`docker compose stop ords && docker compose rm -f ords && docker volume rm ords_ords-config && docker compose up -d ords`
Tout effacer (base + config ORDS)	`docker compose down -v && docker compose up -d --build`
Effacer les jetons OpenCode	`opencode mcp logout ords-mcp`

Critères de succès

Comment savoir que tout marche

/mcp renvoie 401 sans jeton
Les métadonnées de ressource ont resource = http://127.0.0.1:8080/mcp
Le jeton d’accès contient roles2 et permissions incluant le scope MCP
opencode mcp list → connected (OAuth)
database_list correspond aux rôles (FIN → mcp-fin uniquement)
Le SQL sur le pool autorisé fonctionne

Un souci ? Voir le dépannage Comprendre ce qui s’est passé (OAuth)