{"slug":"connectors/AI_CONNECTOR_MCP_FLOW","title":"AI Connector MCP Flow — Marketplace → Onboarding → Execution","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/AI_CONNECTOR_MCP_FLOW.mdx","bytes":17859,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED MARKETPLACE/RUNTIME SNAPSHOT.** The Descope/D1,\n> per-tenant-endpoint and old single-listing flow below must not be implemented.\n> Current publication behavior is defined by\n> [`IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md`](./IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md).\n\nOriginal status: CURRENT\nScope: End-to-end flow for AI-provider MCP connectors (Claude / OpenAI / Perplexity) from marketplace install through governed execution, mapped to what exists in this repo and in the live Cloudflare account.\nCanonical Owner: Platform\nLast Verified: 2026-07-19 (live Cloudflare account inventory + repo audit)\nEvidence Basis: `services/gateway/src/ai-plugin-marketplace.ts`, `services/mcp-pool/`, `services/integration-management-mcp/`, `services/hermes/`, `packages/adk/`, `HERMES.md`, deployed workers `integratewise-anthropic-mcp-prod` / `integratewise-perplexity-mcp-prod` / `integratewise-mcp-pool-prod` / `integratewise-integration-management-mcp-prod`\n**Canonical Reference:** [CANONICAL_PLATFORM_ARCHITECTURE.md](CANONICAL_PLATFORM_ARCHITECTURE.md)\n\n> Downstream of the Canonical Platform Architecture and [HERMES.md](../../HERMES.md).\n> Where this document contradicts them, they win. Hermes orchestrates; Hermes\n> does not own canonical truth. No AI action executes without approval.\n\n---\n\n## 1. The canonical flow\n\n```text\n AI Connector Marketplace\n │\n ▼\n User installs connector\n │\n ▼\n Identity & Authentication\n (Descope / Auth0 / Enterprise SSO)\n │\n ▼\n Tenant Onboarding\n │\n ┌───────────────────┼───────────────────┐\n ▼ ▼ ▼\n Create Tenant Create User Create Workspace\n │ │ │\n └───────────────────┼───────────────────┘\n ▼\n Initialize Spine\n │\n ▼\n Register Connected Systems\n │\n ▼\n Register Capability Fabric\n │\n ▼\n Register MCP Server/Connector\n │\n ▼\n Register AI Runtime (ADK)\n │\n ▼\n Register Governance Policies\n │\n ▼\n Provision Tenant MCP Endpoint\n │\n ▼\n Claude / OpenAI / Perplexity connect\n │\n ▼\n MCP Server / Gateway\n │\n ▼\n Hermes\n (Orchestrator)\n │\n ┌───────────────┬───────────────┬───────────────┐\n ▼ ▼ ▼\n Capability Fabric Context Engine Policy Engine\n │ │ │\n └───────────────┼───────────────┘\n ▼\n ADK Agent Runtime\n │\n ┌───────────────┼────────────────┐\n ▼ ▼ ▼\n Tool Registry Workflow Engine Memory Services\n │ │ │\n └───────────────┼────────────────┘\n ▼\n Spine\n (Memory • Context • Knowledge)\n │\n ▼\n Connector Execution Layer\n │\n ┌───────────────┼──────────────────────────┐\n ▼ ▼ ▼ ▼\n Salesforce Slack GitHub Google Workspace\n │ │ │ │\n └───────────────┼──────────────┼───────────┘\n ▼\n Execution Results\n │\n ▼\n Governance & Approval\n │\n ▼\n Update Spine Memory\n │\n ▼\n Response returned to AI\n```\n\nTwo directions run over the same fabric:\n\n- **Inbound (AI as client):** an AI assistant (Claude, ChatGPT, Perplexity)\n installs the IntegrateWise plugin, gets a tenant, and reaches the workspace\n through the gateway — the marketplace flow above.\n- **Outbound (AI as capability):** IntegrateWise tenants connect AI providers\n as MCP connectors (`anthropic-mcp`, `perplexity-mcp`, `openai-mcp`) whose\n capabilities (reasoning, vision, code, long-context) become tools in the\n Capability Fabric on the **cognitive plane** — subject to the same approval\n gates as every other cognitive capability.\n\n---\n\n## 2. Stage-by-stage: where each piece lives\n\n| # | Stage | Implementation | State |\n| --- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |\n| 1 | AI Connector Marketplace | `services/gateway/src/ai-plugin-marketplace.ts` — plugin manifest (`getPluginManifest`, OAuth via `auth.integratewise.ai`, scopes `iw:connect iw:search iw:act iw:reason iw:sync`), install webhook (`handlePluginInstall`), connector install (`handleConnectorInstall`) | IN REPO + LIVE (gateway-prod) |\n| 2 | User installs connector | `plugin.installed` event → `handlePluginInstall` | IN REPO + LIVE |\n| 3 | Identity & Authentication | Descope: `resolveDescopePrincipal` (gateway), `VITE_DESCOPE_PROJECT_ID` (web); plugin OAuth (PKCE) declared in the manifest | IN REPO + LIVE |\n| 4 | Tenant Onboarding (tenant/user/workspace) | `handlePluginInstall` creates tenant `ai-{platform}-{user_id}` in D1 `tenants`, stores tokens in `ai_platform_tokens`, returns `onboarding_url` → `app.integratewise.ai/onboarding`; full onboarding via `integratewise-tenants` + web activation flow | IN REPO + LIVE |\n| 5 | Initialize Spine | `tenant_spine_config` (D1) written during onboarding; Spine workers + `integratewise-spine-cache` / `integratewise-spine-prod` D1 | IN REPO + LIVE |\n| 6 | Register Connected Systems | Nango-backed catalog + connect sessions (`workspace-spine.ts`, connector service); `integration-management-mcp` (connector/schema/sync/webhook managers) | IN REPO + LIVE |\n| 7 | Register Capability Fabric | `services/gateway/src/workbench-capabilities.ts` + [CAPABILITY_FABRIC.md](CAPABILITY_FABRIC.md); planes `operational` / `cognitive` | IN REPO + LIVE |\n| 8 | Register MCP Server/Connector | MCP Pool `POST /register` with an `MCPServiceManifest`; pre-wired registrations in `services/mcp-pool/src/registrations.ts` | IN REPO + LIVE (see gaps) |\n| 9 | Register AI Runtime (ADK) | `packages/adk` (agent-registry, registry, resolver, spine-cache); `iw-agent-runtime` worker | IN REPO + LIVE |\n| 10 | Register Governance Policies | Gateway HITL orchestrator (approval gates, rejection paths); AGENTS.md hard rules (no approval token → no execution) | IN REPO + LIVE |\n| 11 | Provision Tenant MCP Endpoint | — | **MISSING** (see gaps) |\n| 12 | AI providers connect | Deployed AI provider MCP workers (see §3) | LIVE, **not in repo** |\n| 13 | MCP Server / Gateway | `gateway-prod` routes; `mcp-connector-prod` | IN REPO + LIVE |\n| 14 | Hermes (orchestrator) | `services/hermes` — `orchestrator.ts` (n8n → Durable Objects → direct service-mesh fallback chain), `execution-engine.ts`, `stream.ts` | IN REPO; deployed worker `integratewise-hermes` is stale (May 2026) |\n| 15 | ADK Agent Runtime (tools/workflow/memory) | `packages/adk` + `iw-agent-runtime` + `services/workflow` + `packages/hermes-spine-memory` | IN REPO + LIVE |\n| 16 | Spine (memory/context/knowledge) | Spine workers, `knowledge-prod`, `continuity-prod` | IN REPO + LIVE |\n| 17 | Connector Execution Layer | `connector-prod` + Nango OAuth + `integratewise-webhook-ingress` | IN REPO + LIVE |\n| 18 | Governance & Approval | Approval Gate (HITL) — non-bypassable; results persist only after approval | IN REPO + LIVE |\n| 19 | Update Spine Memory | Session summaries / governed outputs enter the Spine as the third flow (Truth · Context · Knowledge) | IN REPO + LIVE |\n\n---\n\n## 3. The AI provider MCP connector contract (as deployed)\n\n`integratewise-anthropic-mcp-prod` and `integratewise-perplexity-mcp-prod`\n(Hono workers) expose a uniform surface:\n\n```text\nGET /mcp/manifest → MCPServiceManifest:\n id (\"anthropic-mcp\"), provider, version,\n capabilities[] (id, input/output JSON Schema),\n connectionConfig { type: \"api_key\", fields },\n syncConfig { supportsScheduledSync, defaultSyncInterval, syncableData }\nPOST /mcp/invoke → { capability, args, context: { credentials: { apiKey } } }\n → provider API call → { success, data }\nGET /health → { status: \"ok\" }\nPOST /sync → scheduled sync entry point (chat_history / usage / models)\n```\n\nAnthropic capabilities as deployed: `reasoning`, `vision`, `code_generation`,\n`long_context_analysis`, `chat_completion`. Credentials are **per-tenant,\npassed per-invoke** — the workers hold no provider keys.\n\nThis manifest shape is exactly what the MCP Pool registers (`pool.register(manifest, binding)`),\nwhich is how these connectors surface in the marketplace and become\nCapability-Fabric tools on the cognitive plane.\n\n---\n\n## 4. Divergence register (repo ↔ live account)\n\n1. **AI provider MCP workers are not in the monorepo.**\n `integratewise-anthropic-mcp-prod` and `integratewise-perplexity-mcp-prod`\n (deployed 2026-07-18) have no source, wrangler config, or CI here — they\n were deployed from outside this repo. They bundle `hono@4.12.8` from a\n pnpm store path, so they came from _a_ monorepo checkout, just not a\n committed one. **Action: repatriate their source into `services/` so the\n repo is the single source of truth.**\n2. **No OpenAI MCP worker is deployed** despite the flow (and the plugin\n manifest copy) naming Claude / OpenAI / Perplexity. **Action: build+deploy\n `integratewise-openai-mcp` to the same contract (§3).**\n3. **MCP Pool pre-wired bindings were dead config.** `wrangler.toml` declared\n bindings as bare TOML keys, which wrangler ignores — so `registerPreWired`\n skipped everything and the pool started empty. Fixed (same commit as this\n doc) to real `[[services]]` blocks, binding only workers that actually\n exist (`integratewise-integration-management-mcp-prod`,\n `integratewise-spine`). `PROVIDER_MANAGEMENT` and `TASK_MANAGEMENT` stay\n commented until those workers are deployed — a binding to a nonexistent\n worker fails the deploy.\n4. **Per-tenant MCP endpoint provisioning (stage 11) does not exist yet.**\n Today the AI provider MCPs are shared multi-tenant workers keyed by\n per-invoke credentials. A per-tenant endpoint (URL or token-scoped route\n provisioned at onboarding) is the design target, not current behavior.\n5. **The deployed `integratewise-hermes` worker predates the current\n `services/hermes` source** (deployed May 2026; orchestrator has since\n gained the n8n → DO → mesh fallback chain). **Action: redeploy Hermes from\n the repo once its wiring is reviewed.**\n\n---\n\n## 5. Governance invariants (non-negotiable, per AGENTS.md)\n\n- The Twin/AI **proposes**; execution happens only after Approval Gate passes.\n This applies identically to inbound AI assistants (plugin scopes `iw:act`)\n and outbound AI-provider capabilities (cognitive plane, confidence-capped).\n- Hermes coordinates reasoning and execution but never writes canonical truth;\n the Spine is SSOT and memory informs truth without being truth.\n- Every invoke carries tenant context; credentials are tenant-scoped and never\n stored in the MCP workers.\n"}