ChatGPT Custom Connector Setup for Lantern OS MCP

Status: ✅ READY FOR SETUP Last Updated: 2026-06-13 Tested With: OpenAI GPT-4, Claude API

Overview

Lantern OS exposes an OAuth2-secured Model Context Protocol (MCP) server that integrates with ChatGPT custom connectors. This allows ChatGPT to call Lantern OS tools directly within conversations.

System Requirements

✅ All Met:

OAuth2 PKCE flow (S256)
JWT token authentication (HS256, 60-minute TTL)
Standard MCP discovery endpoints
Tool schema validation
Bearer token authorization

Quick Start

Phase 1: Local Development (Current Status)

The system is fully operational for local development and testing.

Setup ChatGPT Connector (Local)

Register OAuth Application
- Visit: https://platform.openai.com/account/apps
- Create new "Custom Integration"
- Name: "Lantern OS MCP"
Configure Connector Settings


   Display Name: Lantern OS MCP

   Description: Access Lantern OS tools through ChatGPT

   Icon URL: https://mcp.lantern-os.net/icon.png (or local)

   

   OAuth Settings:

   - Authorization URL: http://127.0.0.1:8772/oauth/authorize

   - Token URL: http://127.0.0.1:8772/oauth/token

   - Client ID: (generated by OpenAI)

   - Client Secret: (generated by OpenAI)

   - Scopes: read write

   - Redirect URLs: http://127.0.0.1:8772/oauth/callback

   

   API Settings:

   - Base URL: http://127.0.0.1:8772

   - Schema URL: http://127.0.0.1:8772/api/schema

   - Discovery: http://127.0.0.1:8772/.well-known/mcp.json

Test Authentication Flow


   # In ChatGPT, click "Connect" for Lantern OS MCP

   # Authorize at http://127.0.0.1:8772/oauth/authorize?client_id=... 

   # Receive JWT token

   # Test tool calls

Verify Tool Access


   Available Tools:

   - queue_status: Check task queue

   - task_intake: Submit new task

   - dispatch_work: Assign work to agents

   - boot_check: System health check

   - list_skills: Available agent skills

   - get_status: Current system status

   - web_search: Search the web

   - (+ 6 more MCP tools)

Quick self-service registration (Custom GPT)

Alternative to the OpenAI-platform client above (absorbed from .claude/GPT-OAUTH-SETUP.md): the OAuth MCP server can mint a client_id itself — useful for a Custom GPT Action.


   curl "http://127.0.0.1:8772/oauth/register?client_name=MyGPT&redirect_uri=https://oauth.pstmn.io/v1/callback"

In the GPT → Configure → Actions, import the schema from

http://YOUR_HOST:8772/.well-known/mcp or paste .claude/gpt-oauth-mcp-schema.yaml.

Authentication → OAuth: Client ID from step 1, Client Secret blank,

Authorization URL http://YOUR_HOST:8772/oauth/authorize, Token URL http://YOUR_HOST:8772/oauth/token, Scope mcp, Token Exchange Method Default (POST request).

If registration was done on a different host than the GPT reaches

(e.g. ngrok), re-register against the public URL — otherwise you get Invalid client_id.

Phase 2: Production Deployment (Tunnel Fix Required)

Once the Cloudflare tunnel routing issue is resolved, move to HTTPS endpoints.

Setup ChatGPT Connector (Production)

Replace all http://127.0.0.1:8772 with https://mcp.lantern-os.net in:

OAuth configuration
API base URL
Schema/discovery endpoints
Callback URLs


OAuth Settings:

- Authorization URL: https://mcp.lantern-os.net/oauth/authorize

- Token URL: https://mcp.lantern-os.net/oauth/token

- Redirect URLs: https://mcp.lantern-os.net/oauth/callback



API Settings:

- Base URL: https://mcp.lantern-os.net

- Schema URL: https://mcp.lantern-os.net/api/schema

Authentication Flow

OAuth2 with PKCE


┌─────────┐                                 ┌──────────────┐

│ ChatGPT │                                 │   Lantern OS │

│         │                                 │   OAuth      │

└────┬────┘                                 └──────┬───────┘

     │                                              │

     │ 1. Authorize (with code_challenge)         │

     ├─────────────────────────────────────────→  │

     │                                              │

     │ 2. User grants permission                  │

     │                                              │

     │  3. Authorization code                      │

     │ ←─────────────────────────────────────────  │

     │                                              │

     │ 4. Exchange code for token (with code_verifier)

     ├─────────────────────────────────────────→  │

     │                                              │

     │ 5. JWT Token (60-minute TTL)               │

     │ ←─────────────────────────────────────────  │

     │                                              │

     │ 6. Tool call with Bearer token             │

     ├─────────────────────────────────────────→  │

     │                                              │

     │ 7. Tool result                              │

     │ ←─────────────────────────────────────────  │

JWT Token Structure


Header: {

  "alg": "HS256",

  "typ": "JWT"

}



Payload: {

  "sub": "<client_id>",

  "iat": 1686835200,

  "exp": 1686838800,  // 60 minutes

  "scopes": ["read", "write"],

  "issuer": "lantern-os-mcp-oauth"

}

API Endpoints

Discovery

GET http://127.0.0.1:8772/.well-known/oauth-authorization-server

Response:


{

  "issuer": "lantern-os-mcp-oauth",

  "authorization_endpoint": "http://127.0.0.1:8772/oauth/authorize",

  "token_endpoint": "http://127.0.0.1:8772/oauth/token",

  "revocation_endpoint": "http://127.0.0.1:8772/oauth/revoke",

  "scopes_supported": ["read", "write"],

  "response_types_supported": ["code"],

  "grant_types_supported": ["authorization_code"],

  "code_challenge_methods_supported": ["S256"]

}

OAuth Authorize

GET http://127.0.0.1:8772/oauth/authorize

Parameters:


?client_id=<CLIENT_ID>

&redirect_uri=http://127.0.0.1:8772/oauth/callback

&response_type=code

&scope=read+write

&state=<RANDOM_STATE>

&code_challenge=<SHA256_BASE64_HASH>

&code_challenge_method=S256

Response: Redirect to callback with authorization code

OAuth Token

POST http://127.0.0.1:8772/oauth/token

Body:


{

  "grant_type": "authorization_code",

  "code": "<AUTHORIZATION_CODE>",

  "client_id": "<CLIENT_ID>",

  "client_secret": "<CLIENT_SECRET>",

  "code_verifier": "<ORIGINAL_CODE_CHALLENGE_INPUT>",

  "redirect_uri": "http://127.0.0.1:8772/oauth/callback"

}

Response:


{

  "access_token": "eyJhbGci...",

  "token_type": "Bearer",

  "expires_in": 3600,

  "scope": "read write"

}

MCP Tool Discovery

GET http://127.0.0.1:8772/

Response:


{

  "version": "1.0.0",

  "auth": "OAuth 2.0 + PKCE",

  "tools": [

    "queue_status",

    "task_intake",

    "dispatch_work",

    "boot_check",

    "list_skills",

    "get_status",

    "fleet_status",

    "mesh_register_peer",

    "mesh_status",

    "mesh_donate",

    "mesh_prune",

    "update_lantern_os",

    "web_search"

  ]

}

Tool Execution

POST http://127.0.0.1:8772/api/tools/<TOOL_NAME>

Headers:


Authorization: Bearer <JWT_TOKEN>

Content-Type: application/json

Body:


{

  "input": { /* tool-specific parameters */ }

}

Response:


{

  "result": { /* tool result data */ }

}

Testing

Manual Testing with curl


# 1. Get OAuth discovery

curl http://127.0.0.1:8772/.well-known/oauth-authorization-server



# 2. Initiate OAuth flow (returns redirect with code)

curl -i "http://127.0.0.1:8772/oauth/authorize?client_id=test&response_type=code&code_challenge=xyz&code_challenge_method=S256"



# 3. Exchange code for token (requires client_secret)

curl -X POST http://127.0.0.1:8772/oauth/token \

  -H "Content-Type: application/json" \

  -d '{

    "grant_type": "authorization_code",

    "code": "<AUTH_CODE>",

    "client_id": "test",

    "code_verifier": "original_challenge_input"

  }'



# 4. Call tool with token

curl -X POST http://127.0.0.1:8772/api/tools/queue_status \

  -H "Authorization: Bearer <JWT_TOKEN>" \

  -H "Content-Type: application/json" \

  -d '{}'

Integration Test

Run the CI/CD validation workflow:


# Triggers automatically on master push

# Or manually: GitHub Actions → Validate System Integration → Run workflow

Troubleshooting

Issue: OAuth Discovery Endpoint Returns 404

Cause: OAuth server not running on port 8772

Solution:


# Verify services running

lsof -i :8772



# Start services

npm start --prefix apps/lantern-garage

Issue: PKCE Code Challenge Mismatch

Cause: Original code_challenge input doesn't match stored hash

Solution:


# Use same code_verifier that generated code_challenge

# SHA256(code_verifier) == code_challenge (base64url encoded)

Issue: JWT Token Expired

Cause: Token TTL isminutes

Solution:


# Request new token via OAuth token endpoint

# Implement token refresh in ChatGPT connector

Issue: Bearer Token Invalid

Cause: Token not properly included in Authorization header

Solution:


# Correct format:

Authorization: Bearer eyJhbGci...



# Verify token is JWT signed with MCP_OAUTH_JWT_SECRET

Environment Configuration

Verify .env has these variables:


# MCP OAuth Server

MCP_OAUTH_PORT=8772

MCP_OAUTH_JWT_SECRET=your_secret_key_here

MCP_OAUTH_ISSUER=lantern-os-mcp-oauth

MCP_OAUTH_TOKEN_TTL=60

MCP_OAUTH_HOST=127.0.0.1



# MCP Server

MCP_SERVER_PORT=8771

MCP_SERVER_HOST=127.0.0.1



# Public tunnel (for production)

MCP_PUBLIC_BASE_URL=https://mcp.lantern-os.net



# LLM Providers (for tool execution)

ANTHROPIC_API_KEY=sk-ant-...

OPENAI_API_KEY=sk-...

GEMINI_API_KEY=...

Security Considerations

✅ Implemented:

OAuth2 PKCE (Proof Key for Code Exchange) prevents authorization code interception
JWT tokens with HS256 HMAC signature
60-minute token TTL for automatic expiration
Bearer token required for all tool calls
State parameter validation for CSRF protection
HTTPS enforced in production (Cloudflare tunnel)

⚠️ Recommendations:

Store client_secret securely (not in code)
Implement token refresh endpoint for long sessions
Use HTTPS only in production
Monitor token usage and revoke compromised tokens
Implement rate limiting on OAuth endpoints
Add audit logging for all tool calls
Disable dynamic auto-registration (/oauth/register) for production — remove

the auto-register block in src/mcp_server/server_oauth.py (~line 470)

Support

For issues with:

OAuth implementation: Check src/mcp_server/server_oauth.py
Tool registration: Check src/mcp_server/server.py
Tunnel routing: Check ~/.cloudflared/config.yml
CI/CD validation: Run .github/workflows/validate-system-integration.yml

ChatGPT Custom Connector Setup for Lantern OS MCP

Overview

System Requirements

Quick Start

Phase 1: Local Development (Current Status)

Setup ChatGPT Connector (Local)

Quick self-service registration (Custom GPT)

Phase 2: Production Deployment (Tunnel Fix Required)

Setup ChatGPT Connector (Production)

Authentication Flow

OAuth2 with PKCE

JWT Token Structure

API Endpoints

Discovery

OAuth Authorize

OAuth Token

MCP Tool Discovery

Tool Execution

Testing

Manual Testing with curl

Integration Test

Troubleshooting

Issue: OAuth Discovery Endpoint Returns 404

Issue: PKCE Code Challenge Mismatch

Issue: JWT Token Expired

Issue: Bearer Token Invalid

Environment Configuration

Security Considerations

Production Deployment Checklist

Support

References