{"slug":"architecture/MCP_POOL_OPERATIONAL_SPINE_FABRIC_CONTRACT","title":"MCP Pool — Operational Spine Capability Fabric Contract","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/MCP_POOL_OPERATIONAL_SPINE_FABRIC_CONTRACT.mdx","bytes":14093,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Frozen implementation contract for PR #109  \n**Public boundary:** `https://mcp.integratewise.ai`  \n**Internal boundary:** Cloudflare service bindings, queues, D1, and KV only\n\n## 1. Decision\n\nThe MCP Pool is not a directory of unrelated MCP servers and it is not a client-side\nfan-out proxy. It is the internal capability control plane coupled to the Operational\nSpine Fabric.\n\n```text\nAI host / MCP client\n        |\n        v\nIW-Spine-Network MCP\nexact 19 semantic tools\n        |\n        v\nMCP POOL / CAPABILITY CONTROL PLANE\n  - ADK capability registry\n  - ADK capability resolver\n  - tenant/workspace context\n  - connector and marketplace eligibility\n  - governance and approval policy\n  - runtime and version resolution\n  - audit/correlation envelope\n        |\n        +---------------------+---------------------+\n        |                     |                     |\n        v                     v                     v\nOperational Spine        Cognitive Fabric      Operational Runtimes\nSpine/Pipeline            Twin/Intelligence     Integration/Task/Workflow\nMemory/Knowledge          Agent Runtime         Provider/Marketplace\nPromotion queues          Agent logs            Connectors/Webhooks\n```\n\nThe Pool may route to internal MCP implementations, native Workers, queues, Durable\nObjects, and governed workflows. A downstream runtime does not need to expose an MCP\ntransport. The Pool uses a runtime adapter for each internal contract.\n\n## 2. Public versus internal contracts\n\n### Public contract\n\nThe only client configuration is the remote IW-Spine-Network MCP endpoint. The public\ntool catalog remains exactly 19 semantic tools.\n\nNo client receives:\n\n- raw provider MCP tools;\n- Cloudflare service topology;\n- direct provider URLs or credentials;\n- tenant identity through local environment variables;\n- the internal capability registry;\n- local filesystem, Playwright, memory, sequential-thinking, Docker, `uvx`, `npx`, or\n  localhost MCP processes.\n\n### Internal contract\n\nThe Pool owns stable capability discovery and governed routing. Internal implementation\ncapabilities may be larger than the 19 public tools, but they remain hidden behind the\nsemantic ingress.\n\n## 3. Components embedded in the Pool\n\nThese are control-plane libraries and state, not downstream service registrations.\n\n### 3.1 ADK Capability Registry\n\nCanonical source: `packages/adk/src/registry.ts`.\n\nThe registry owns stable capability names, required scopes, minimum tier, connector\nrequirements, primary route, and permitted fallback. Provider tool names are not the\nstable contract.\n\n### 3.2 ADK Capability Resolver\n\nCanonical source: `packages/adk/src/resolver.ts`.\n\nEvery invocation runs through:\n\n1. capability existence;\n2. tenant plan/tier gate;\n3. connected-connector gate;\n4. initial-sync state;\n5. primary route selection;\n6. explicitly permitted fallback.\n\nThe Pool must import `@integratewise/adk`; it must not maintain a second independent\ncapability policy engine.\n\n### 3.3 Operational Spine context resolver\n\nThe Pool resolves tenant/workspace state from the Operational Spine fabric:\n\n- subscription tier;\n- enabled domains and entity types;\n- connected connectors;\n- connector sync state;\n- published connector/application state;\n- workspace connection and installation state;\n- role, scopes, approval authority, and policy version.\n\nKV may cache this context, but the cache is not authority. The authenticated ingress and\nSpine state are authority.\n\n### 3.4 Agent registry\n\nCanonical source: `packages/adk/src/agent-registry.ts`.\n\nThe registry maps a stable capability to an available agent/runtime. It contains routing\nmetadata only. It owns no logs, memory, or private reasoning.\n\n### 3.5 Runtime adapter registry\n\nA resolved ADK route target is translated into a typed internal contract. The Pool must\nnot assume every service implements `POST /invoke`.\n\nRequired adapter kinds:\n\n- `mcp_invoke` — internal MCP Workers with a typed `/invoke` endpoint;\n- `service_http` — native Worker HTTP contract;\n- `spine_read` — governed Operational Spine reads;\n- `pipeline_command` — normalized Spine write or reconciliation command;\n- `queue_publish` — deferred/evented execution;\n- `workflow_start` — long-running governed workflow;\n- `agent_runtime` — authenticated Twin/agent execution;\n- `knowledge_query` — governed memory/knowledge retrieval;\n- `marketplace_installation` — installation state-machine transition.\n\n## 4. Coupled runtime nodes\n\n### 4.1 Operational Spine and Pipeline\n\nBindings/state:\n\n- `SPINE`\n- `PIPELINE`\n- Spine cache D1\n- ADK/connector-state KV\n\nResponsibilities:\n\n- canonical entity and relationship reads;\n- timeline and change reads;\n- normalized write proposals;\n- sole governed write path through Pipeline;\n- result reconciliation into the Spine;\n- emission of `spine.written` and downstream lifecycle events.\n\nThe Pool never writes canonical truth directly.\n\n### 4.2 ADK and Capability Resolver\n\nEmbedded dependency:\n\n- `@integratewise/adk`\n\nResponsibilities:\n\n- stable capability contract;\n- plan, connector, sync, and scope eligibility;\n- runtime target and fallback selection;\n- agent/tool resolution.\n\n### 4.3 Integration Manager and Provider Manager\n\nBindings:\n\n- `INTEGRATION_MANAGEMENT`\n- `PROVIDER_MANAGEMENT`\n\nResponsibilities:\n\n- connector install/configure/enable/disable/remove;\n- provider app and OAuth lifecycle;\n- sync orchestration;\n- webhook lifecycle;\n- schema registration and normalization;\n- authorised provider invocation through an existing connection.\n\nThe Integration Manager already exposes an internal `/invoke` contract and is the\ncanonical operational adapter for connector lifecycle. Client-side vendor MCP entries\nmust not bypass it.\n\n### 4.4 Connector Marketplace catalog and publication state\n\nSources:\n\n- `packages/connectors/src/catalog.ts` and catalog types;\n- Operational Spine `spine_connector_registry` publication state;\n- workspace connection state;\n- Marketplace Installation state.\n\nResponsibilities in the Pool:\n\n- determine whether a connector/app is code-backed, published, installed, connected,\n  pending, degraded, or unavailable;\n- expose only capabilities whose connector/application prerequisites are satisfied;\n- route activation to Marketplace Installation and Integration Manager;\n- keep raw credentials behind Provider Management/Integration Manager.\n\nThe marketplace UI is a discovery surface. It is not the capability execution engine.\n\n### 4.5 Plugin and MCP marketplace applications\n\nSources/services:\n\n- IW-Spine-Network Plugin/MCP publication contract;\n- `MARKETPLACE_INSTALLATION` runtime;\n- host installation and consent records;\n- delegated capability bindings recorded in the Spine Network.\n\nResponsibilities in the Pool:\n\n- check that the host/plugin installation is active and consented;\n- resolve the installation to the correct tenant/workspace/Spine Network;\n- include channel and installation lineage in audit metadata;\n- permit only declared IW semantic capabilities;\n- reject credential inheritance or unrestricted host-app discovery.\n\nThe Pool does not execute marketplace UI code and does not ingest arbitrary host tools.\n\n### 4.6 Twin Orchestrator, Intelligence, and Agent Runtime\n\nBindings:\n\n- `TWIN_ORCHESTRATOR`\n- `INTELLIGENCE`\n- `AGENT_RUNTIME`\n\nResponsibilities:\n\n- observe, reason, propose, and coordinate;\n- resolve contextual Twin requests;\n- prepare immutable action plans;\n- invoke user-facing agent runtime only with authenticated actor and tenant authority;\n- never execute operational writes without governance.\n\nTwin Orchestrator is cognitive orchestration. Intelligence is the consolidated\nthink/act/govern runtime. Agent Runtime owns user-facing Twin/agent sessions and Durable\nObject state. They are separate runtime adapters, not interchangeable aliases.\n\n### 4.7 Agent and execution logs\n\nSources:\n\n- Twin/agent session logger;\n- invocation audit envelope;\n- task/workflow execution history;\n- Cloudflare observability.\n\nEvery Pool invocation records or emits:\n\n- correlation id;\n- tenant, workspace, user, role, and installation lineage;\n- public semantic tool and resolved internal capability;\n- selected runtime and implementation version;\n- policy and approval decision;\n- input hash/redaction metadata;\n- outcome status, duration, retry/fallback state, and evidence refs.\n\nThe Pool must not store private chain-of-thought. Logs contain decisions, actions,\nevidence, errors, and performance metadata only.\n\n### 4.8 Memory, Knowledge, Continuity, and promotion queues\n\nBindings/resources:\n\n- `KNOWLEDGE`\n- `CONTINUITY`\n- `MEMORY_PROMOTE` queue\n- `KNOWLEDGE_QUEUE` where applicable\n- Pipeline promotion consumer\n\nResponsibilities:\n\n- retrieve permitted conversational and organisational memory;\n- query governed knowledge;\n- propose memory with evidence and lineage;\n- publish eligible Spine write events to `MEMORY_PROMOTE`;\n- let Pipeline's promotion engine score the seven promotion signals;\n- stage approval-required memory;\n- promote approved memory and index it;\n- record memory-promotion audit rows.\n\nThe Pool does not write `org_memory` directly and does not bypass the promotion or\napproval lifecycle.\n\n### 4.9 Task and Workflow runtimes\n\nBindings:\n\n- `TASK_MANAGEMENT`\n- `WORKFLOW`\n\nResponsibilities:\n\n- scheduled and condition-driven task lifecycle;\n- deferred execution;\n- retries, cancellation, DLQ, metrics, and execution history;\n- governed workflow start and result reconciliation.\n\n## 5. Required Pool binding model\n\n### Hard readiness dependencies\n\nThe Pool is not ready without:\n\n- Operational Spine context/state;\n- ADK registry/resolver;\n- Pipeline write/reconciliation path;\n- Integration Manager;\n- Provider Manager;\n- Knowledge/Continuity read path;\n- audit/event sink.\n\n### Capability-scoped dependencies\n\nThe Pool remains generally ready but marks capabilities degraded/unavailable when these\nare absent:\n\n- Marketplace Installation;\n- Twin Orchestrator;\n- Agent Runtime;\n- Task Management;\n- Workflow;\n- optional connector/provider runtimes.\n\nReadiness is therefore two-dimensional:\n\n1. **control-plane readiness** — can the Pool resolve authority and policy safely?\n2. **capability readiness** — is a specific implementation available and healthy?\n\n## 6. Invocation lifecycle\n\n```text\n1. MCP Connector authenticates actor and maps one of 19 public tools to intent.\n2. Pool loads tenant/workspace/installation context from Operational Spine fabric.\n3. ADK resolves stable capability eligibility and target class.\n4. Marketplace and connector state qualify the capability for this workspace.\n5. Governance determines read, proposal, approval, or forbidden mode.\n6. Agent registry/version resolver selects a healthy implementation.\n7. Runtime adapter invokes service, queue, workflow, or agent runtime.\n8. Pool records audit/execution metadata.\n9. Result is normalized to evidence.\n10. Operational outcomes reconcile through Pipeline into Spine.\n11. Eligible Spine writes enter memory-promotion lifecycle.\n12. MCP Connector returns bounded semantic output through the public 19-tool facade.\n```\n\nNo denial falls back to a direct vendor call.\n\n## 7. Explicitly rejected topology\n\nThe following topology is invalid:\n\n```text\nClient\n  +-> Cloudflare MCP\n  +-> GitHub MCP\n  +-> Google MCP\n  +-> provider MCPs\n  +-> local filesystem/playwright/memory processes\n  +-> IW MCP\n```\n\nIt bypasses the IntegrateWise trust boundary, fragments identity and audit, exposes raw\nprovider semantics, and prevents Operational Spine continuity.\n\nThe accepted topology is:\n\n```text\nClient -> IW MCP -> MCP Pool -> governed capability fabric -> provider/runtime\n```\n\n## 8. Repository reconciliation findings\n\nThe following existing code must not remain canonical without correction:\n\n1. `packages/spine-network/README.md` still advertises a local `npx`/stdio setup even\n   though the current distribution contract is remote MCP. Update it to remote-first and\n   move stdio to a clearly separate compatibility/operator profile or retire it.\n2. `services/gateway/src/ai-plugin-marketplace.ts` contains a legacy hard-coded connector\n   list, direct Nango session creation, locally constructed tenant identities, and direct\n   token persistence. Replace this path with Gateway identity resolution + Marketplace\n   Installation + Integration Manager + credential wall.\n3. `services/marketplace-installation/wrangler.toml` contains placeholder D1 ids. The\n   runtime is implemented but is not a production-ready hard dependency until real\n   bindings are provisioned and verified.\n4. The projection-engine capability resolver is a presentation/readiness resolver and\n   contains connector-status logic drift. It must not replace the ADK execution resolver.\n5. MCP Pool's current registrations list internal tool names but do not yet compose ADK,\n   marketplace eligibility, agent registry, audit, memory promotion, and runtime adapters.\n\n## 9. Implementation sequence for PR #109\n\n1. Add `@integratewise/adk` to MCP Pool and make ADK resolution mandatory.\n2. Add Operational Spine tenant-context adapter using D1/KV or a dedicated Spine Fabric\n   service contract.\n3. Add runtime adapter registry; stop assuming every downstream service uses `/invoke`.\n4. Add bindings for Pipeline, Knowledge, Continuity, Intelligence, Twin Orchestrator,\n   Agent Runtime, Workflow, and Marketplace Installation.\n5. Mark optional runtimes capability-degraded instead of failing the whole Pool.\n6. Add marketplace/connector eligibility resolver from code catalog + Spine publication\n   state + installation/connection state.\n7. Add audit event emission and agent/execution log correlation.\n8. Add promotion queue publishing only after successful reconciled Spine writes.\n9. Wire MCP Connector semantic actions to stable ADK capabilities.\n10. Remove stale client fan-out and legacy plugin bypass paths.\n11. Verify contract tests, package tests, Cloudflare bindings, and an authenticated E2E\n    read -> proposal -> approval -> execution -> Spine reconciliation -> memory promotion.\n"}