{"slug":"developers/CHATGPT_CONNECTOR_GUIDE","title":"ChatGPT Connector Registration for IntegrateWise","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/CHATGPT_CONNECTOR_GUIDE.mdx","bytes":9316,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Overview\n\nIntegrateWise MCP Server is registered as a **ChatGPT Connector** allowing enterprise ChatGPT users to access:\n- **spine.query** — unified operational data\n- **spine.get** — entity details\n- **memory.search** — organizational knowledge\n- **memory.propose** — capture insights\n- **spine.connected_sources** — connection status\n\nChatGPT can then use its own connectors (Salesforce, Gmail, etc.) to reach external tools, with IntegrateWise in the middle as the **continuity brain**.\n\n## Architecture\n\n```\nChatGPT Enterprise\n  ├─ ChatGPT Connectors (Salesforce, Gmail, etc.)\n  └─ IntegrateWise MCP Server (our connector)\n       ├─ spine.query → D1 vault → Salesforce/Gmail data\n       ├─ memory.search → vector DB → org knowledge\n       └─ memory.propose → proposals table → triage bot\n\nResult: ChatGPT can read unified data AND capture insights\n```\n\n## Registration Steps\n\n### 1. Create Connector Metadata\n\nGo to **ChatGPT Enterprise Settings** → **Connectors** → **Create Connector**\n\nFill in:\n\n```\nName: IntegrateWise Spine\nDescription: Unified operational truth — query sales data, accounts, memories\n\nCategory: Data Integration\nAuthentication: OAuth 2.0\n\nAPI Endpoint: https://mcp.integratewise.ai\nAuth Endpoint: https://mcp.integratewise.ai/oauth/authorize\nToken Endpoint: https://mcp.integratewise.ai/oauth/token\n\nSchema Endpoint: https://mcp.integratewise.ai/schema.json\n```\n\n### 2. Configure OAuth (if using token-based auth)\n\n**Option A: API Key Auth (simpler)**\n\n```\nAuthentication Type: API Key\nHeader Name: Authorization\nHeader Format: Bearer {token}\n```\n\nUsers will paste their MCP token in ConnectorSettings.\n\n**Option B: OAuth (more secure)**\n\nCreate OAuth endpoints in gateway:\n\n```\nPOST /oauth/authorize\n  ↓\nGenerate authorization code\n↓ (user grants permission in ChatGPT)\n  ↓\nPOST /oauth/token (code) → MCP token\n```\n\n### 3. Register Tools\n\nChatGPT will query `https://mcp.integratewise.ai/schema.json` to discover tools.\n\nCreate endpoint:\n\n```typescript\n// services/mcp-connector/src/handlers/schema.ts\nexport async function getSchema(actor: SpineMcpActor) {\n  return {\n    tools: [\n      {\n        name: \"spine.query\",\n        description: \"Query unified operational data\",\n        inputSchema: { /* from spine-mcp-server.ts */ }\n      },\n      {\n        name: \"spine.get\",\n        description: \"Get entity details\"\n        inputSchema: { /* ... */ }\n      },\n      // ... rest of tools\n    ]\n  }\n}\n```\n\n### 4. Deploy MCP Server\n\nThe MCP server is already built in `services/mcp-connector/src/spine-mcp-server.ts`.\n\nDeploy to CF Workers:\n\n```bash\ncd services/mcp-connector\nnpm run deploy\n# → https://mcp.integratewise.ai\n```\n\nEnsure bindings:\n- `CACHE_DB` → D1 database\n- `SPINE_ENCRYPTION_KEY` → secrets\n- `VECTORIZE` → vector index\n- `CACHE` → KV namespace\n- `MCP_SERVICE_SECRET` → shared secret with gateway\n\n### 5. Test in ChatGPT\n\n1. **Connect Connector:**\n   - ChatGPT Settings → Connectors → IntegrateWise Spine\n   - Authorize (OAuth) or paste API key\n   - Test connection\n\n2. **Test Tools:**\n   - Ask ChatGPT: \"What accounts are in the Spine?\"\n   - ChatGPT calls `spine.query` with entity_type=\"account\"\n   - Returns list of accounts with status, health, MRR\n\n3. **Query Examples:**\n   - \"Find stalled deals in Salesforce\"\n   - \"What patterns have we seen in renewals?\"\n   - \"Summarize recent activities for Acme Corp\"\n\n## User Flow (ChatGPT Enterprise)\n\n```\n1. User opens ChatGPT Enterprise\n2. Selects \"IntegrateWise Spine\" connector\n3. AuthenticatesOAuth) → gets MCP token\n4. Token stored in ChatGPT session\n5. User asks question (e.g., \"Show me high-risk accounts\")\n6. ChatGPT calls spine.query with MCP token\n   ↓ (validated in mcp-connector/src/middleware/auth.ts)\n7. Query executes against encrypted vault\n8. Results returned to ChatGPT\n9. ChatGPT generates natural language response\n```\n\n## Example Conversation\n\n**User:** \"What are my top 3 expansion opportunities this quarter?\"\n\n**ChatGPT (using IntegrateWise):**\n\n```\nCalling: spine.query({\n  entity_type: \"account\",\n  status: \"active\",\n  health_trend: \"improving\",\n  arr_over: 100000,\n  limit: 3\n})\n\nResult: [\n  { id: \"acc-123\", name: \"Acme Corp\", arr: 250000, health_score: 0.85 },\n  { id: \"acc-456\", name: \"TechCorp\", arr: 180000, health_score: 0.78 },\n  { id: \"acc-789\", name: \"InnovateCo\", arr: 150000, health_score: 0.82 }\n]\n```\n\n**ChatGPT Response:**\n\n> Your top 3 expansion opportunities this quarter are:\n> \n> 1. **Acme Corp** ($250k ARR, 85% health)\n>    - Healthy trend, receptive to upsells\n>    - Recommendation: Schedule EBR next week\n> \n> 2. **InnovateCo** ($150k ARR, 82% health)\n>    - Rising health score indicates engagement\n>    - Recommendation: Present new feature set\n> \n> 3. **TechCorp** ($180k ARR, 78% health)\n>    - Steady health, growth potential\n>    - Recommendation: Evaluate expansion product fit\n\n## Tier-Based Feature Access\n\n**Free Tier:** (no ChatGPT access)\n\n**Starter Tier:**\n- ✅ spine.query\n- ✅ spine.get\n- ✅ spine.summary\n- ✅ spine.connected_sources\n- ✅ memory.search (semantic)\n- ✅ memory.propose (to governance)\n\n**Pro Tier:**\n- All starter features +\n- ✅ Advanced memory queries\n- ✅ Custom entity types\n- ✅ Report generation\n\n**Enterprise Tier:**\n- All features +\n- ✅ Full audit logs\n- ✅ Custom connectors\n- ✅ Dedicated MCP instance\n\n## Security\n\n1. **Token Validation:**\n   - 15-minute expiry\n   - HMAC-SHA256 signed\n   - Validates on every tool call\n   - See `services/mcp-connector/src/middleware/auth.ts`\n\n2. **Tenant Isolation:**\n   - All queries scoped to tenant_id\n   - Hard wall: tenant_id mismatch → 403 Forbidden\n   - No cross-tenant data leakage\n\n3. **Role-Based Access:**\n   - Actor permissions derived from role + tier\n   - Fine-grained checks in `middleware/actor.ts`\n   - Tool access gated by permissions\n\n4. **Encrypted Vault:**\n   - All data at rest encrypted (AES-256)\n   - Decryption key in CF Secrets (not queryable)\n   - Vault reads always decrypt before returning\n\n## Monitoring\n\nMonitor via CF Analytics:\n\n```\nGET /api/v1/mcp/metrics\n→ tool calls per hour\n→ error rates\n→ latency p50/p95\n→ tenant activity\n```\n\nAdd to dashboard:\n\n```typescript\n// services/gateway/src/metrics.ts\nexport async function getMcpMetrics(tenantId: string, hoursBack: number = 24) {\n  // Query CF Analytics for MCP calls\n  // Return: call_count, error_count, avg_latency, tools_used\n}\n```\n\n## Troubleshooting\n\n**\"Connector not authorized\"**\n- User didn't authenticate OAuth\n- Token expired (> 15 min)\n- Solution: Re-authorize in ChatGPT settings\n\n**\"Entity type not configured\"**\n- Tenant doesn't have entity type enabled\n- Solution: Admin enables in Settings → Spine Config\n\n**\"Connector not connected\"**\n- Tenant doesn't have data source enabled (e.g., Salesforce)\n- Tool tried to query disconnected source\n- Solution: Connect source in /connectors\n\n**High latency**\n- Vault queries slow (encrypted field searches)\n- Solution: Pre-populate vectorize for memory searches\n\n## Integration with Onboarding\n\nWhen user completes onboarding:\n1. Role + connectors stored in D1\n2. tenant_spine_config populated\n3. User can now authenticate ChatGPT connector\n4. ChatGPT sees only authorized entity types + connectors\n\n## Next: Auto-Approve Workflow\n\nWhen ChatGPT calls `memory.propose()` to capture insight:\n\n```\nmemory.propose({\n  content_type: \"insight\",\n  title: \"Renewal Pattern: EBR → 85% renewal rate\",\n  body: \"Accounts with quarterly EBRs renew at 85% vs 60% baseline\",\n  confidence: 0.92\n})\n  ↓\nTriage Bot scores proposal\n  ↓\nScore ≥ 0.85 → auto-approve to org memory\n  ↓\nNext user asks: \"What renewal patterns have we learned?\"\n  ↓\nChatGPT calls memory.search() → finds this insight\n```\n\nThis closes the loop: ChatGPT captures knowledge, promotes to org memory, answers future questions.\n\n## Files Summary\n\n### Created\n- `services/mcp-connector/src/middleware/auth.ts` (209 lines) - Token validation\n- `services/mcp-connector/src/middleware/actor.ts` (327 lines) - Actor resolution\n\n### Existing (Already Built)\n- `services/mcp-connector/src/spine-mcp-server.ts` - MCP tool definitions\n- `apps/web/lib/auth/connector-approval.ts` - OAuth flow\n\n### To Create\n- `services/mcp-connector/src/handlers/schema.ts` - ChatGPT schema endpoint\n- `services/gateway/src/oauth.ts` - OAuth authorize/token endpoints\n- `services/mcp-connector/src/handlers/proposal.ts` - Enhanced memory.propose\n\n## Next Steps\n\n1. ✅ Deploy MCP server to CF Workers\n2. ⏳ Create schema endpoint (handlers/schema.ts)\n3. ⏳ Register in ChatGPT Connector UI\n4. ⏳ Test OAuth flow\n5. ⏳ Verify tenant isolation + permission gating\n6. ⏳ Load test (1000+ concurrent ChatGPT connections)\n7. ⏳ Enable memory.propose governance loop\n\n## Success Metrics\n\n- ChatGPT connects successfully (< 1% auth failures)\n- Queries execute < 500ms p50, < 2s p95\n- Tenant isolation enforced (0 cross-tenant leaks)\n- Memory proposals flow through triage bot (> 80% auto-approved)\n- User engagement: avg 5+ queries/user/day\n"}