Local ChatGPT development

OpenAI Secure MCP Tunnel connects ChatGPT to the MCP server on your machine over outbound HTTPS. No public DNS record, inbound firewall rule, ngrok account, or local TLS certificate is required.

This workflow deliberately uses the Solibo dev environment:

  • The MCP process and all widget resources come from the local checkout.
  • Browser-facing OAuth remains on https://mcp.dev.solibo.io.
  • OAuth and pending-action state use the shared dev DynamoDB table.
  • Pending upload bytes use the dev S3 bucket.
  • Solibo API calls target the dev backend.
  • Widgets, writes, customer communications, and real mutation execution are enabled.

Production still starts the normal MainKt entry point. The tunnel launcher is used only by Gradle’s run task, and the tunnel secret is created only for dev.

One-time OpenAI setup

  1. Open Platform tunnel settings.
  2. Create a tunnel and associate both the owning Platform organization and the ChatGPT workspace where it will be tested.
  3. Ensure the operator has Tunnels Read + Use. Creating or editing the tunnel also requires Tunnels Read + Manage.
  4. Create a restricted project API key for the tunnel runtime with Tunnels Read + Use.
  5. Enable ChatGPT developer mode for the target workspace.

The tunnel ID must look like tunnel_0123456789abcdef0123456789abcdef.

Store the tunnel credentials

CDK manages the dev secret in the isolated SoliboHomeMcpLocalDev-dev stack:

cd infra
npm ci
npx cdk deploy SoliboHomeMcpLocalDev-dev --require-approval never -c env=dev
cd ..

The deployed secret name is solibo-home-mcp-dev-openai-tunnel. Replace its generated placeholder through the AWS Secrets Manager console with this JSON:

{
  "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
  "apiKey": "sk-..."
}

Add organizationId only when the tunnel key requires an explicit OpenAI organization header:

{
  "tunnelId": "tunnel_0123456789abcdef0123456789abcdef",
  "apiKey": "sk-...",
  "organizationId": "org_..."
}

Do not put the API key in .env, a Gradle property, CDK context, or the Git repository. The launcher reads it directly from Secrets Manager and supplies it only to the tunnel-client process environment.

Run

From the repository root:

aws sso login
./gradlew run

On each invocation Gradle:

  1. Installs exact npm dependencies when needed.
  2. Builds all 21 widget resources as standalone HTML with a fresh resource URI version, avoiding stale ChatGPT widget caches.
  3. Downloads OpenAI tunnel-client v0.0.10 once and verifies the release archive SHA-256 for the current macOS/Linux architecture.
  4. Reads the dev service token and tunnel credentials from Secrets Manager.
  5. Exports the active AWS CLI credentials for local DynamoDB, S3, and SES access.
  6. Starts the local MCP server and waits for /health.
  7. Starts the tunnel and waits for its /readyz endpoint.
  8. Prints the loopback tunnel admin UI URL. Ctrl-C stops both processes.

In ChatGPT, open Plugins, create a developer-mode app, choose Tunnel for the connection, then select this tunnel or paste its ID. Choose OAuth authentication; discovery continues through the public dev authorization server.

Overrides

The defaults should work for the normal dev account. These variables are available when needed:

Variable Purpose
SOLIBO_LOCAL_AWS_PROFILE AWS CLI profile used for all lookups and temporary credentials
SOLIBO_LOCAL_PORT Local MCP port; defaults to 8080
SOLIBO_LOCAL_TUNNEL_SECRET_NAME Alternate Secrets Manager secret name
SOLIBO_LOCAL_DEBUG=true Print a launcher stack trace after a startup failure

The AWS session credentials exported at startup do not refresh inside a running MCP process. Re-run aws sso login and restart ./gradlew run after they expire.

Secure MCP Tunnel is for private and developer-mode testing. It does not replace the stable public HTTPS endpoint required for plugin submission.

Solibo AS