{"slug":"architecture/IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT","title":"IW-Spine-Network Plugin and MCP Marketplace Contract","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.mdx","bytes":17091,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Current derived publication and host-surface contract  \n**Date:** 2026-07-29  \n**Authority:** `ARCHITECTURE_LOCK.md`, `IMPLEMENTATION_CONTRACT_v1.1.md` and `CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`\n\n## 1. Locked identity\n\nThe public distribution identity is **IW-Spine-Network**.\n\nIt is published as two channel-native artifacts backed by one Platform and one\nsemantic tool contract:\n\n| Distribution lane                          | Published artifact          | User experience                                                                                                                                                       |\n| ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Plugin marketplace / directory**         | **IW-Spine-Network Plugin** | An MCP-backed app with a focused embedded control surface, workflow skills and optional templates. The host remains the conversational controller.                    |\n| **MCP marketplace / registry / directory** | **IW-Spine-Network MCP**    | A remote MCP exposing the exact **IW Spine Tools** 19-tool contract, text/JSON fallback, optional focused MCP App UI and a launch path to the full browser Workbench. |\n\nThe Plugin and MCP packages are separate marketplace artifacts, but they do not\ncreate separate backends, truth stores, tool semantics or governance paths.\n\nCurrent OpenAI terminology calls the discovery surface the **Plugin Directory**: a plugin may include apps, skills and app templates. An app uses MCP-backed tools and may provide interactive UI inside ChatGPT. See [Plugins in ChatGPT and Codex](https://help.openai.com/en/articles/20001256), [Apps in ChatGPT](https://help.openai.com/en/articles/11487775-connectors-in) and [Build with the Apps SDK](https://help.openai.com/en/articles/12515353-build-with-the-apps-sdk.iso).\n\n## 2. Shared Platform rule\n\nBoth artifacts use the deployed IntegrateWise Platform:\n\n```text\nHost or browser\n→ Descope / marketplace identity hand-off\n→ Gateway tenant and membership resolution\n→ Configuration + Integration + Activation\n→ Operational Spine\n→ Governed Canonical Spine\n→ Projection / Capability contracts\n→ Governance approval\n→ Hermes execution\n→ provider outcome and reconciliation\n```\n\nInstallation does not copy Fortress, Gateway, Pipeline, Triage, Governance,\nHermes or the internal MCP Pool into the host.\n\nThe Customer Zero setup is the **reference activation profile** used to prove\nthe package. For an external user, installation creates or resolves an isolated\ncustomer tenant and instantiates the same configuration/runtime shape. It never\nshares Customer Zero data, credentials, memory, queues, cache or audit history.\n\nOrdinary tenants run on shared stateless Platform Workers with strict tenant\nisolation. A separate physical deployment is created only when an approved\nisolation policy requires it. “Quick deploy” means tenant activation,\nconfiguration compilation and host-surface instantiation—not an uncontrolled\nclone of the Platform for every click.\n\n## 3. Plugin marketplace runtime\n\n### 3.1 Package contents\n\nThe **IW-Spine-Network Plugin** contains:\n\n1. the OAuth/identity and tenant activation contract;\n2. an MCP-backed app with focused interactive UI resources for tables, pickers, approvals, progress,\n   network status and Workbench launch;\n3. IW workflow skills and, where supported, app templates;\n4. the exact 19-tool **IW Spine Tools** manifest;\n5. privacy, terms, support, screenshots, tool descriptions and reviewer\n   instructions.\n\nThe public MCP tool inventory behind the Plugin remains exactly 19 tools. UI\nresources are additive metadata/resources; they do not expand the public tool\ncount.\n\n### 3.2 Installation sequence\n\n```text\nUser selects IW-Spine-Network Plugin in a Plugin marketplace/directory\n→ host/workspace policy permits installation\n→ user reviews capabilities and connects the IW app\n→ OAuth resolves existing IW identity or creates onboarding session\n→ Gateway resolves or creates the isolated tenant/workspace\n→ Activation applies the Customer Zero-proven reference profile\n→ Spine Network discovery resolves authorised IW connections/capabilities\n→ host renders the controlled IW surface above its conversation/agent runtime\n→ user works through the host conversation and the IW embedded surface\n```\n\n**ChatGPT control surface:** when ChatGPT is the host, ChatGPT remains the\nconversational and agent controller. The IW-created surface is a focused\ncontrolled interface through which ChatGPT may request declared IW tools. It\ndoes not receive IW credentials, internal pools or direct provider access.\n\nThe surface is an MCP App UI rendered in a host sandbox. It may appear above or\nalongside the host experience, but it is not a DOM patch, browser extension or\nreplacement for ChatGPT. It cannot read the host page's DOM, cookies, local\nstorage or private app registry.\n\nThe host decides when to call approved IW tools. The widget may send user intent to the host, update bounded model context or call declared IW server tools through the host bridge. It never calls Neon, D1/KV, credentials, providers, Hermes or internal MCP Pool directly.\n\n### 3.3 Controlling applications already connected to the host\n\nIf ChatGPT is connected to ten or twenty applications, IW-Spine-Network does\nnot automatically inherit those credentials or receive an unrestricted list of\nthem.\n\nApplications can participate in an IW-controlled workflow through three\nexplicit paths:\n\n| Path                             | Requirement                                                                                             | Persistence                                                                 |\n| -------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |\n| **Host composition**             | The host exposes the other app in the same conversation and is allowed to orchestrate it with IW        | Host/session-scoped unless an outcome is explicitly stored                  |\n| **Delegated capability binding** | The host provides a supported discovery/delegation contract and the user/admin grants IW the capability | Recorded as a tenant-scoped Spine Network binding with source and authority |\n| **Direct IW connector**          | The user connects the provider through IntegrateWise Connector Marketplace / Integration Manager        | Persistent IW connection, synchronization, health and governed capabilities |\n\nDiscovery is therefore **capability discovery**, not credential scraping.\nDuplicate connections to the same provider/account are grouped only after\nprovider workspace, account, user, tenant, authority and provenance match. The\nUI shows every origin and the selected precedence/merge policy.\n\n### 3.4 Controller and approval boundary\n\nInside ChatGPT, ChatGPT is the conversational controller and may coordinate\ndeclared apps. IW-Spine-Network remains the continuity, context, capability and\ngovernance boundary for IW operations.\n\n```text\nUser intent in ChatGPT\n→ ChatGPT selects an approved IW tool/widget\n→ IW prepares context or a proposal\n→ embedded UI shows evidence, affected systems and plan\n→ user explicitly approves the exact action\n→ Governance mints a scoped approval token\n→ Hermes executes through the authorised connector/capability\n→ outcome returns to ChatGPT and re-enters the Spine lifecycle\n```\n\nNo host, model, skill, widget or confidence threshold bypasses human approval.\n\n## 4. MCP marketplace and browser Workbench runtime\n\nThe **IW-Spine-Network MCP** is the remote MCP package for MCP marketplaces,\nregistries and compatible clients. The **browser Workbench** is its full\nstandalone control surface when a host cannot or should not render the complete\nproduct experience.\n\n```text\nUser discovers IW-Spine-Network MCP in an MCP marketplace/registry\n→ connects the remote MCP server\n→ completes IW authentication, tenant selection and consent\n→ Activation resolves the Customer Zero-proven reference profile\n→ client receives the permitted 19-tool catalog\n→ ordinary MCP clients receive text/JSON results\n→ compatible hosts may render focused MCP App widgets\n→ Open Workbench launches the full IntegrateWise browser application\n```\n\nThe browser Workbench communicates with Gateway through the typed frontend client and does not depend on ChatGPT to operate. Twin remains silent and contextual within that Workbench.\n\nThe MCP listing does not publish the internal 55-tool MCP Pool, raw provider\ntools, credentials, internal topology or autonomous write access.\n\n## 5. Provider and developer marketplace packages\n\nProvider and developer marketplaces such as Vercel, Notion, Coda and GitHub\nreceive a channel-native IW package only when that marketplace requires its own\ninstallation, OAuth, webhook, lifecycle or agent-tool semantics. These packages\ndo not replace the Plugin or MCP artifacts.\n\nFor the Vercel channel, publish a provider integration called\n**IW-Spine-Network** with a native product called **IW-Spine-Network MCP** when\nthe intended user experience is to install IntegrateWise in Vercel and use its\ngoverned Spine tools through Vercel Agent Tools.\n\n| Published component                        | Why it exists                                                                                            | Platform implementation                                                                                            |\n| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| **IW-Spine-Network** listing               | Marketplace discovery, legal/support metadata, install entry point                                       | Listing metadata, documentation, privacy policy, EULA, support contact, configuration and redirect URLs            |\n| **IW-Spine-Network MCP** native product    | Makes the approved IW MCP tool surface available to an installed Vercel team through Agent Tools         | Cloudflare-hosted native-integration server plus the OAuth-protected public IW Spine Tools MCP contract            |\n| **Vercel connector**                       | Brings authorized Vercel project/deployment/operational context into IntegrateWise                       | Integration Manager connector; it normalizes Vercel data through Pipeline and exposes governed Vercel capabilities |\n| **Installation and configuration surface** | Lets a team choose the IW tenant/workspace, permitted Vercel projects, sync policy, and activation scope | Cloudflare-hosted configuration application; invokes Configuration, Integration, and Activation Managers           |\n| **Webhook endpoint**                       | Receives Vercel installation, lifecycle, and allowed resource events                                     | Verified ingress → Gateway → Integration Manager/Pipeline; no browser-mediated secrets                             |\n| **MCP tool manifest**                      | Declares the semantic tools exposed in Vercel Agent Tools                                                | Maps only to the frozen public IW Spine Tools; never exposes internal Pool/provider/credential tools               |\n\nThe Marketplace product and Vercel connector are two directions of one connection:\n\n```text\nVercel Agent Tools → IW-Spine-Network MCP native product → Gateway → permitted Spine context/capabilities\nVercel project events/data → Vercel connector → Pipeline → Spine → Workbench/Twin\n```\n\n### 5.1 Vercel installation, consent, and identity\n\n```text\nVercel team installs IW-Spine-Network MCP\n  → Vercel installation identity is verified server-to-server\n  → user signs in to IntegrateWise or creates an IW tenant\n  → administrator selects target IW tenant/workspace and permitted Vercel projects\n  → consent records scopes, source access, policy, and data-sharing purpose\n  → Installation ↔ IW tenant/workspace ↔ Vercel connection is recorded\n  → MCP tools and Vercel connector are enabled through Discovery\n```\n\nRequired records are: Vercel installation/team reference, IW tenant/workspace reference, connection id, allowed project/resource scope, granted capabilities, consent/policy version, credential reference, and audit lineage. Secrets and access tokens remain in the credential wall; they are never published to the listing, browser, or MCP tool result.\n\n## 6. Surface responsibility matrix\n\n| Responsibility                     | Host surface                                | Browser Workbench                           | IntegrateWise Platform                 |\n| ---------------------------------- | ------------------------------------------- | ------------------------------------------- | -------------------------------------- |\n| Conversation and model interaction | Host                                        | Optional frontend interaction only          | Model/provider routing policy          |\n| Render focused IW controls         | Host sandbox + IW UI resource               | Product frontend                            | Supplies typed data/resources          |\n| Full tables/pages/canvas           | Launch or bounded widget only               | Owns full experience                        | Projection contracts                   |\n| Identity hand-off                  | Host + OAuth                                | Descope                                     | Gateway resolves tenant/membership     |\n| Capability discovery               | Host-visible apps plus IW response          | IW discovery response                       | Spine Network resolver                 |\n| Connector credentials              | Never                                       | Never                                       | Credential wall                        |\n| Canonical truth                    | Never                                       | Never                                       | Neon through Governed Spine Writers    |\n| Proposal and approval              | Shows exact plan and captures user decision | Shows exact plan and captures user decision | Governance validates and mints token   |\n| External execution                 | Never direct                                | Never direct                                | Hermes through authorised capabilities |\n\n## 7. Connector marketplace distinction\n\nThe IntegrateWise **Connector Marketplace** is not either public distribution\nlane. It is the in-product tray used to choose and authorize provider\nconnections.\n\n```text\nPlugin Marketplace     → install IW-Spine-Network Plugin + embedded host UI\nMCP Marketplace        → connect IW-Spine-Network MCP + optional widget /\n                         standalone browser Workbench\nConnector Marketplace  → choose provider connectors inside IntegrateWise\nProvider Marketplace   → install a provider-native IW package only when provider\n                         OAuth/webhook/installation semantics require it\n```\n\n## 8. Publication gates\n\nNeither public artifact is publishable until Customer Zero proves:\n\n1. clean install into a new tenant;\n2. OAuth, consent, tenant isolation and revocation;\n3. exactly 19 public tools;\n4. embedded UI sandbox/CSP behavior and no-UI fallback;\n5. capability discovery with partial/failure states;\n6. duplicate-connection grouping and provenance;\n7. action evidence, explicit approval and Hermes execution;\n8. Operational-to-Canonical promotion and outcome reconciliation;\n9. privacy, support, screenshots, reviewer instructions and version rollback;\n10. Development, Customer Zero and Customer Production isolation.\n\n## 9. Required public copy\n\n### Plugin marketplace / directory\n\n```text\nName: IW-Spine-Network\nPackage: IW-Spine-Network Plugin\nType: Plugin with MCP-backed app, focused interactive UI, workflow skills and\n      optional templates\nAction: Install and connect\nPromise: Run an IntegrateWise control surface inside the AI host while the host\n         remains the conversation and agent controller.\n```\n\n### MCP marketplace / registry\n\n```text\nName: IW-Spine-Network\nPackage: IW-Spine-Network MCP\nType: Remote MCP server + optional MCP App UI\nTechnical surface: IW Spine Tools (exactly 19 tools)\nAction: Connect MCP / Open Workbench\nPromise: Connect any compatible MCP client to one governed tenant Spine Network\n         and open the full standalone browser Workbench when needed.\n```\n\nThe repository, Customer Zero/external audience, deployment and promotion split\nis governed by\n`CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md`.\n"}