Guide d’auto-hébergement OOMOL OpenConnector

OOMOL OpenConnector est un service connector open-source et auto-hébergeable. Utilisez-le lorsque des agents ou outils internes doivent appeler de vrais services externes tout en gardant les identifiants provider, permissions et historique d’exécution dans votre propre environnement. Il expose des actions typées pour des services comme GitHub, Gmail, Notion, Hacker News, Ably, Abstract et A-Leads via MCP ou HTTP.

Les agents voient les schémas, scopes, statuts d’exécution et libellés de compte sûrs ; les tokens provider bruts, permissions d’action et historiques d’exécution restent dans votre frontière de déploiement.

Ce que cela fournit

• Un runtime qui expose les actions provider via MCP, HTTP, OpenAPI et une console web.
• Un stockage des identifiants pour clés API, identifiants personnalisés, connexions OAuth2 et providers sans auth.
• Des schémas d’action typés pour que les agents découvrent ce qu’ils peuvent appeler avant de l’appeler.
• L’identité de connexion et les scopes pour que les utilisateurs et agents voient sous quel compte une action s’exécutera.
• Un transit temporaire de fichiers pour les actions qui nécessitent des URL de fichiers.
• Des logs d’exécution récents avec résumés d’entrée expurgés et erreurs provider.
• Un catalogue de providers avec des exécutors locaux qui se chargent uniquement lorsqu’une action est utilisée.

Commencez par choisir où exécuter le runtime, puis configurez le stockage, le contrôle d’accès, les connexions provider et le point d’entrée MCP ou HTTP exposé aux agents.

Choisir une cible de déploiement

Préparer le runtime

Avant de déployer, choisissez ces valeurs :

Traitez la base de données runtime comme sensible. Sans OOMOL_CONNECT_ENCRYPTION_KEY, OOMOL OpenConnector fonctionne encore, mais les secrets provider sont stockés dans un fichier SQLite local sensible.

Exécuter avec Docker Compose

Clonez le dépôt OOMOL OpenConnector, entrez dans le répertoire du projet et démarrez le runtime :

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
docker compose up --build

Ouvrez la console web :

http://localhost:3000

Ouvrez la référence API générée :

http://localhost:3000/docs

Vérifiez le runtime avec une action sans auth :

curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Docker Compose stocke l’état runtime dans le volume connector-data. Le conteneur stocke SQLite ici :

/app/data/connect.sqlite

Pour un déploiement serveur privé, définissez au minimum le token admin et la clé de chiffrement avant de démarrer :

OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

Lorsque le runtime est exposé via un domaine public ou un tunnel, définissez aussi l’origine publique :

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

L’image Docker écoute sur 0.0.0.0 dans le conteneur. Contrôlez l’accès externe avec le firewall hôte, un reverse proxy ou votre plateforme de conteneurs.

Protéger l’accès admin et runtime

Les clients HTTP admin appellent /api, /docs ou la console web avec :

Authorization: Bearer replace-with-an-admin-token

Créez des runtime tokens pour les agents et clients de type SDK depuis l’onglet Access de la console web. Le token est affiché une seule fois ; seul un hash est stocké.

Vous pouvez aussi en créer un via l’admin API :

curl -s -X POST http://localhost:3000/api/runtime-tokens \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"name":"Claude Desktop"}'

Les clients runtime appellent ensuite /v1 ou /mcp avec :

Authorization: Bearer oct_...

Pour les scripts de bootstrap et la compatibilité ascendante, OOMOL_CONNECT_RUNTIME_TOKEN reste accepté :

OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_RUNTIME_TOKEN="replace-with-a-runtime-token" \
docker compose up --build

Limitez les actions que les agents peuvent exécuter :

OOMOL_CONNECT_ALLOWED_ACTIONS="hackernews.*,github.get_current_user" docker compose up --build

Bloquez des actions précises même lorsqu’une allowlist plus large les inclut :

OOMOL_CONNECT_ALLOWED_ACTIONS="github.*" \
OOMOL_CONNECT_BLOCKED_ACTIONS="github.delete_repository" \
docker compose up --build

Connecter un provider par clé API

GitHub est un exemple compact de clé API, car il peut utiliser un personal access token.

Inspectez le contrat du provider :

curl -s http://localhost:3000/api/providers/github \
  -H 'authorization: Bearer replace-with-an-admin-token'

Stockez la connexion GitHub par défaut :

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

Appelez GitHub via le runtime :

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'authorization: Bearer oct_...' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Vérifiez les connexions configurées et l’identité de compte sûre exposée aux agents :

curl -s http://localhost:3000/api/connections \
  -H 'authorization: Bearer replace-with-an-admin-token'

Connexions nommées

Ajoutez connectionName lorsque le même provider nécessite plusieurs comptes :

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","connectionName":"work","values":{"apiKey":"github_pat_..."}}'

Sélectionnez ce compte pendant l’exécution :

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'authorization: Bearer oct_...' \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Le paramètre de requête alias est aussi accepté.

Connecter un provider OAuth

Les providers OAuth utilisent votre propre app OAuth provider. Listez d’abord les providers compatibles OAuth et copiez l’expectedRedirectUri du service :

curl -s http://localhost:3000/api/oauth/configs \
  -H 'authorization: Bearer replace-with-an-admin-token'

Avec le port par défaut, GitHub utilise cette URL de callback :

http://localhost:3000/oauth/callback

Collez l’URL de callback exacte retournée par /api/oauth/configs dans l’app OAuth provider. Si vous changez PORT, HOST ou exposez le runtime via une autre origine, définissez OOMOL_CONNECT_ORIGIN avant de démarrer le runtime et relisez l’URL de callback.

Stockez le client OAuth localement :

curl -s -X PUT http://localhost:3000/api/oauth/configs/github \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

Démarrez l’autorisation :

curl -s -X POST http://localhost:3000/api/oauth/authorizations \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

Ouvrez l’authorizationUrl retournée dans un navigateur. Après la redirection du provider vers l’URL de callback, OOMOL OpenConnector stocke le credential OAuth comme connexion par défaut.

Pour stocker le résultat OAuth comme connexion nommée, incluez connectionName :

curl -s -X POST http://localhost:3000/api/oauth/authorizations \
  -H 'authorization: Bearer replace-with-an-admin-token' \
  -H 'content-type: application/json' \
  -d '{"service":"github","connectionName":"work"}'

Donner les outils à un agent

Pour les clients compatibles MCP, pointez le client vers :

http://localhost:3000/mcp

Le serveur MCP expose des outils orientés découverte :

• list_apps
• search_actions
• get_action_guide
• execute_action

Prévisualisez les métadonnées d’outils MCP :

curl -s http://localhost:3000/mcp/tools \
  -H 'authorization: Bearer oct_...'

Pour les clients HTTP, utilisez l’API runtime /v1 :

curl -s http://localhost:3000/v1/actions \
  -H 'authorization: Bearer oct_...'

Chaque action a un guide Markdown local avec le schéma d’entrée, les scopes, les permissions provider, l’identité de connexion courante et des exemples de requêtes :

curl -s http://localhost:3000/api/actions/github.get_current_user/agent.md \
  -H 'authorization: Bearer replace-with-an-admin-token'

La console web peut aussi copier des exemples cURL, TypeScript et prompts d’agent pour chaque action.

Exécuter depuis les sources

Utilisez le workflow source lorsque vous développez OOMOL OpenConnector ou des provider executors. Utilisez Node.js 22 ou plus récent.

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
npm install
npm run build:web
npm run dev

npm install et npm run dev créent les fichiers générés locaux lorsqu’ils manquent ou sont obsolètes.

Lorsque vous exécutez depuis les sources, l’état runtime est stocké dans :

./data/connect.sqlite

Utilisez un autre répertoire de données avec :

OOMOL_CONNECT_DATA_DIR=/path/to/data npm run dev

Définissez les mêmes variables d’environnement admin, chiffrement, origine, runtime token et action policy que ci-dessus.

Déployer sur Cloudflare Workers

Cloudflare Workers est pris en charge comme cible de déploiement pour les métadonnées et l’état runtime.

Clonez le dépôt, créez les ressources Cloudflare et déployez :

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
cp wrangler.example.jsonc wrangler.local.jsonc
npm run generate:catalog
npm run build:web
npx wrangler d1 create oomol-connect
npx wrangler r2 bucket create oomol-connect-transit-files
npx wrangler d1 migrations apply oomol-connect --remote
npm run deploy:cloudflare

Avant le déploiement, mettez à jour le fichier ignoré wrangler.local.jsonc avec le D1 database_id retourné par Cloudflare.

Définissez les secrets avec Wrangler :

npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY

Cloudflare utilise les mêmes noms de variables d’environnement pour l’origine, les auth tokens, l’action policy, les limites de fichiers de transit et le chiffrement des credentials. PORT, HOST et OOMOL_CONNECT_DATA_DIR sont des réglages locaux propres à Node.

Le runtime Worker sert les métadonnées du catalogue, les endpoints de métadonnées /api et /v1, les connexions, runtime tokens, config et état OAuth, les fichiers de transit sur R2 et le registre généré des provider action executors. Configurez une règle de cycle de vie R2 pour le bucket de transit si vous voulez nettoyer automatiquement les fichiers de transit expirés non lus.

Exploiter le déploiement

Gardez ces enregistrements disponibles pour le support et la reprise :

Pour les actions d’upload de fichier, les fichiers de transit locaux sont stockés sous OOMOL_CONNECT_DATA_DIR/files et nettoyés par âge. Ajustez la durée de vie et la taille d’upload avec OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS et OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES.

Dépannage