OOMOL OpenConnector セルフホスティングガイド

OOMOL OpenConnector は、オープンソースでセルフホスト可能な connector service です。provider credentials、permissions、execution history を自分の環境内に置いたまま、agents や internal tools が実際の外部サービスを呼び出す必要がある場合に使用します。GitHub、Gmail、Notion、Hacker News、Ably、Abstract、A-Leads などのサービス向け typed actions を MCP または HTTP で公開します。

Agents には schemas、scopes、execution status、安全な account labels が見えます。raw provider tokens、action permissions、execution history は deployment boundary の内側に残ります。

提供されるもの

• MCP、HTTP、OpenAPI、web console を通じて provider actions を公開する runtime。
• API keys、custom credentials、OAuth2 connections、no-auth providers の credential storage。
• Agents が呼び出す前に呼び出し可能な内容を発見できる typed action schemas。
• Users と agents が action の実行 account を確認できる connection identity と scopes。
• file URLs を必要とする actions のための temporary file transit。
• redacted input summaries と provider errors を含む recent run logs。
• action 使用時にのみ読み込まれる local executors 付き provider catalog。

まず runtime の実行場所を選び、storage、access control、provider connections、agent-facing MCP または HTTP entry point を設定します。

deployment target を選ぶ

runtime を準備する

deploy 前に以下の値を決めます。

runtime database は sensitive として扱ってください。OOMOL_CONNECT_ENCRYPTION_KEY がなくても OOMOL OpenConnector は動作しますが、provider secrets は sensitive な local SQLite file に保存されます。

Docker Compose で実行する

OOMOL OpenConnector repository を clone し、project directory に入り、runtime を起動します。

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

web console を開きます。

http://localhost:3000

生成された API reference を開きます。

http://localhost:3000/docs

no-auth action で runtime を確認します。

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

Docker Compose は runtime state を connector-data volume に保存します。container は SQLite を以下に保存します。

/app/data/connect.sqlite

private server deployment では、少なくとも admin token と encryption key を設定してから起動します。

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

runtime を public domain または tunnel で公開する場合は、public origin も設定します。

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

Docker image は container 内で 0.0.0.0 に bind します。外部アクセスは host firewall、reverse proxy、container platform で制御してください。

admin と runtime access を保護する

Admin HTTP clients は /api、/docs、web console を次の header で呼び出します。

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

Agents と SDK-style clients 用の runtime tokens は web console の Access tab から作成します。token は 1 回だけ表示され、hash のみ保存されます。

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"}'

Runtime clients は /v1 または /mcp を次で呼び出します。

Authorization: Bearer oct_...

bootstrap scripts と backward compatibility のため、OOMOL_CONNECT_RUNTIME_TOKEN も引き続き受け付けます。

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

Agents が実行できる actions を制限します。

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

広い allowlist に含まれる場合でも、特定 actions を block できます。

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

API-key provider を接続する

GitHub は personal access token を使えるため、簡潔な API-key example です。

provider contract を確認します。

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

default GitHub connection を保存します。

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_..."}}'

runtime 経由で GitHub を呼び出します。

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

設定済み connections と agents に公開される safe account identity を確認します。

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

名前付き接続

同じ provider に複数 accounts が必要な場合は connectionName を追加します。

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_..."}}'

実行時にその account を選択します。

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":{}}'

alias query parameter も使用できます。

OAuth provider を接続する

OAuth providers は自分の provider OAuth app を使用します。まず OAuth-capable providers を一覧表示し、service の expectedRedirectUri をコピーします。

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

default port では、GitHub はこの callback URL を使います。

http://localhost:3000/oauth/callback

/api/oauth/configs が返した正確な callback URL を provider OAuth app に貼り付けます。PORT、HOST を変更した場合、または別 origin で runtime を公開した場合は、runtime 起動前に OOMOL_CONNECT_ORIGIN を設定し、callback URL を再度読み取ってください。

OAuth client を local に保存します。

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":"..."}'

authorization を開始します。

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"}'

返された authorizationUrl を browser で開きます。provider が callback URL に redirect した後、OOMOL OpenConnector は OAuth credential を default connection として保存します。

OAuth result を named connection として保存するには、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"}'

agent に tools を渡す

MCP-capable clients では client を次に向けます。

http://localhost:3000/mcp

MCP server は discovery-oriented tools を公開します。

• list_apps
• search_actions
• get_action_guide
• execute_action

MCP tool metadata を preview します。

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

HTTP clients では /v1 runtime API を使います。

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

各 action には、input schema、scopes、provider permissions、current connection identity、request examples を含むローカル Markdown ガイドがあります。

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

web console から各 action の cURL、TypeScript、agent prompt examples もコピーできます。

source から実行する

OOMOL OpenConnector または provider executors を開発する場合は source workflow を使います。Node.js 22 以上を使用してください。

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

npm install と npm run dev は、missing または stale な local generated files を作成します。

source から実行する場合、runtime state は次に保存されます。

./data/connect.sqlite

別の data directory を使う場合:

OOMOL_CONNECT_DATA_DIR=/path/to/data npm run dev

上記と同じ admin、encryption、origin、runtime token、action policy の environment variables を設定します。

Cloudflare Workers に deploy する

Cloudflare Workers は metadata と runtime-state deployment target としてサポートされています。

repository を clone し、Cloudflare resources を作成して deploy します。

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

deploy 前に、Cloudflare が返した D1 database_id を ignored wrangler.local.jsonc file に設定します。

Wrangler で secrets を設定します。

npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY

Cloudflare は origin、auth tokens、action policy、transit file limits、credential encryption に同じ environment variable names を使います。PORT、HOST、OOMOL_CONNECT_DATA_DIR は local Node-only settings です。

Worker runtime は catalog metadata、/api と /v1 metadata endpoints、connections、runtime tokens、OAuth config と state、R2-backed transit files、生成された provider action executor registry を提供します。未読の期限切れ transit files を自動削除したい場合は、transit bucket に R2 lifecycle rule を設定してください。

deployment を運用する

support と recovery のため、以下の records を利用できる状態にしてください。

file-upload actions では、local transit files は OOMOL_CONNECT_DATA_DIR/files 配下に保存され、age によって削除されます。lifetime と upload size は OOMOL_CONNECT_TRANSIT_FILE_TTL_SECONDS と OOMOL_CONNECT_TRANSIT_FILE_MAX_BYTES で調整します。

トラブルシューティング