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 を設定してから起動します。

これらの例は Bash で実行してください。実際の認証情報は非表示の入力プロンプトでのみ入力し、シェルコマンドやコマンドログに記載しないでください。

(
  set -eu
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_ENCRYPTION_KEY: " OOMOL_CONNECT_ENCRYPTION_KEY
  echo
  test -n "$OOMOL_CONNECT_ENCRYPTION_KEY"
  export OOMOL_CONNECT_ENCRYPTION_KEY
  docker compose up --build
)

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

(
  set -eu
  export OOMOL_CONNECT_ORIGIN="https://connect.example.com"
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_ENCRYPTION_KEY: " OOMOL_CONNECT_ENCRYPTION_KEY
  echo
  test -n "$OOMOL_CONNECT_ENCRYPTION_KEY"
  export OOMOL_CONNECT_ENCRYPTION_KEY
  read -r -s -p "OOMOL_CONNECT_RUNTIME_TOKEN: " OOMOL_CONNECT_RUNTIME_TOKEN
  echo
  test -n "$OOMOL_CONNECT_RUNTIME_TOKEN"
  export OOMOL_CONNECT_RUNTIME_TOKEN
  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 から作成することもできます。

以下の認証付きリクエストには Python 3 と curl 7.76.0 以降が必要です。これらの例で使用する —fail-with-body オプションは、このバージョン以降で利用できます。シークレットは非表示の入力で読み取り、標準入力から curl に渡します。認証情報はコマンドライン引数やシェル履歴に含まれません。

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'name': 'Claude Desktop'}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/api/runtime-tokens', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY

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

Authorization: Bearer oct_...

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

(
  set -eu
  read -r -s -p "OOMOL_CONNECT_ADMIN_TOKEN: " OOMOL_CONNECT_ADMIN_TOKEN
  echo
  test -n "$OOMOL_CONNECT_ADMIN_TOKEN"
  export OOMOL_CONNECT_ADMIN_TOKEN
  read -r -s -p "OOMOL_CONNECT_RUNTIME_TOKEN: " OOMOL_CONNECT_RUNTIME_TOKEN
  echo
  test -n "$OOMOL_CONNECT_RUNTIME_TOKEN"
  export OOMOL_CONNECT_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 を確認します。

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/providers/github'],
    input=config, text=True, check=True,
)
PY

default GitHub connection を保存します。

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'authType': 'api_key', 'values': {'apiKey': None}}
payload["values"]["apiKey"] = getpass.getpass("GitHub API key: ")
if not payload["values"]["apiKey"]:
    raise SystemExit("An API key is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'PUT', 'http://localhost:3000/api/connections/github', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
payload = {'input': {}}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/v1/actions/github.get_current_user', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/connections'],
    input=config, text=True, check=True,
)
PY

名前付き接続

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
payload = {'authType': 'api_key', 'connectionName': 'work', 'values': {'apiKey': None}}
payload["values"]["apiKey"] = getpass.getpass("GitHub API key: ")
if not payload["values"]["apiKey"]:
    raise SystemExit("An API key is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'PUT', 'http://localhost:3000/api/connections/github', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
payload = {'input': {}}
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
config += "data = " + json.dumps(json.dumps(payload)) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'POST', 'http://localhost:3000/v1/actions/github.get_current_user', '--header', 'x-oo-connector-alias: work', '--header', 'content-type: application/json'],
    input=config, text=True, check=True,
)
PY

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 します。

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/mcp/tools'],
    input=config, text=True, check=True,
)
PY

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("Runtime token: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/v1/actions'],
    input=config, text=True, check=True,
)
PY

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

python3 - <<'PY'
import getpass
import json
import subprocess
import warnings

warnings.simplefilter("error", getpass.GetPassWarning)
token = getpass.getpass("OOMOL_CONNECT_ADMIN_TOKEN: ")
if not token:
    raise SystemExit("A token is required")
config = "header = " + json.dumps("authorization: Bearer " + token) + "\n"
subprocess.run(
    ['curl', '--disable', '--silent', '--show-error', '--fail-with-body', '--config', '-', '--request', 'GET', 'http://localhost:3000/api/actions/github.get_current_user/agent.md'],
    input=config, text=True, check=True,
)
PY

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 install
npm run generate:catalog
npm run build:web
npx wrangler d1 create oomol-connect
npx wrangler r2 bucket create oomol-connect-transit-files

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

初期設定中は Worker を非公開にしてください。ローカルの Wrangler 設定で workers_dev と preview_urls を false にし、公開ルートやカスタムドメインを設定しないでください。以下の3つの secret をすべて設定するまで公開アクセスを許可しないでください。

npx wrangler d1 migrations apply oomol-connect --remote --config wrangler.local.jsonc
npm run deploy:cloudflare

Wrangler で secrets を設定します。

npx wrangler secret put OOMOL_CONNECT_ADMIN_TOKEN --config wrangler.local.jsonc
npx wrangler secret put OOMOL_CONNECT_RUNTIME_TOKEN --config wrangler.local.jsonc
npx wrangler secret put OOMOL_CONNECT_ENCRYPTION_KEY --config wrangler.local.jsonc

3つの secret を設定した後、ローカル設定で必要な公開ルートを有効にして再デプロイしてください。

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 で調整します。

トラブルシューティング