Current

MCP Pool — Operational Spine Capability Fabric Contract

Status: Frozen implementation contract for PR #109
Public boundary: https://mcp.integratewise.ai
Internal boundary: Cloudflare service bindings, queues, D1, and KV only

1. Decision

The MCP Pool is not a directory of unrelated MCP servers and it is not a client-side
fan-out proxy. It is the internal capability control plane coupled to the Operational
Spine Fabric.

AI host / MCP client
        |
        v
IW-Spine-Network MCP
exact 19 semantic tools
        |
        v
MCP POOL / CAPABILITY CONTROL PLANE
  - ADK capability registry
  - ADK capability resolver
  - tenant/workspace context
  - connector and marketplace eligibility
  - governance and approval policy
  - runtime and version resolution
  - audit/correlation envelope
        |
        +---------------------+---------------------+
        |                     |                     |
        v                     v                     v
Operational Spine        Cognitive Fabric      Operational Runtimes
Spine/Pipeline            Twin/Intelligence     Integration/Task/Workflow
Memory/Knowledge          Agent Runtime         Provider/Marketplace
Promotion queues          Agent logs            Connectors/Webhooks

The Pool may route to internal MCP implementations, native Workers, queues, Durable
Objects, and governed workflows. A downstream runtime does not need to expose an MCP
transport. The Pool uses a runtime adapter for each internal contract.

2. Public versus internal contracts

Public contract

The only client configuration is the remote IW-Spine-Network MCP endpoint. The public
tool catalog remains exactly 19 semantic tools.

No client receives:

raw provider MCP tools;
Cloudflare service topology;
direct provider URLs or credentials;
tenant identity through local environment variables;
the internal capability registry;
local filesystem, Playwright, memory, sequential-thinking, Docker, uvx, npx, or
localhost MCP processes.

Internal contract

The Pool owns stable capability discovery and governed routing. Internal implementation
capabilities may be larger than the 19 public tools, but they remain hidden behind the
semantic ingress.

3. Components embedded in the Pool

These are control-plane libraries and state, not downstream service registrations.

3.1 ADK Capability Registry

Canonical source: packages/adk/src/registry.ts.

The registry owns stable capability names, required scopes, minimum tier, connector
requirements, primary route, and permitted fallback. Provider tool names are not the
stable contract.

3.2 ADK Capability Resolver

Canonical source: packages/adk/src/resolver.ts.

Every invocation runs through:

capability existence;
tenant plan/tier gate;
connected-connector gate;
initial-sync state;
primary route selection;
explicitly permitted fallback.

The Pool must import @integratewise/adk; it must not maintain a second independent
capability policy engine.

3.3 Operational Spine context resolver

The Pool resolves tenant/workspace state from the Operational Spine fabric:

subscription tier;
enabled domains and entity types;
connected connectors;
connector sync state;
published connector/application state;
workspace connection and installation state;
role, scopes, approval authority, and policy version.

KV may cache this context, but the cache is not authority. The authenticated ingress and
Spine state are authority.

3.4 Agent registry

Canonical source: packages/adk/src/agent-registry.ts.

The registry maps a stable capability to an available agent/runtime. It contains routing
metadata only. It owns no logs, memory, or private reasoning.

3.5 Runtime adapter registry

A resolved ADK route target is translated into a typed internal contract. The Pool must
not assume every service implements POST /invoke.

Required adapter kinds:

mcp_invoke — internal MCP Workers with a typed /invoke endpoint;
service_http — native Worker HTTP contract;
spine_read — governed Operational Spine reads;
pipeline_command — normalized Spine write or reconciliation command;
queue_publish — deferred/evented execution;
workflow_start — long-running governed workflow;
agent_runtime — authenticated Twin/agent execution;
knowledge_query — governed memory/knowledge retrieval;
marketplace_installation — installation state-machine transition.

4. Coupled runtime nodes

4.1 Operational Spine and Pipeline

Bindings/state:

SPINE
PIPELINE
Spine cache D1
ADK/connector-state KV

Responsibilities:

canonical entity and relationship reads;
timeline and change reads;
normalized write proposals;
sole governed write path through Pipeline;
result reconciliation into the Spine;
emission of spine.written and downstream lifecycle events.

The Pool never writes canonical truth directly.

4.2 ADK and Capability Resolver

Embedded dependency:

@integratewise/adk

Responsibilities:

stable capability contract;
plan, connector, sync, and scope eligibility;
runtime target and fallback selection;
agent/tool resolution.

4.3 Integration Manager and Provider Manager

Bindings:

INTEGRATION_MANAGEMENT
PROVIDER_MANAGEMENT

Responsibilities:

connector install/configure/enable/disable/remove;
provider app and OAuth lifecycle;
sync orchestration;
webhook lifecycle;
schema registration and normalization;
authorised provider invocation through an existing connection.

The Integration Manager already exposes an internal /invoke contract and is the
canonical operational adapter for connector lifecycle. Client-side vendor MCP entries
must not bypass it.

4.4 Connector Marketplace catalog and publication state

Sources:

packages/connectors/src/catalog.ts and catalog types;
Operational Spine spine_connector_registry publication state;
workspace connection state;
Marketplace Installation state.

Responsibilities in the Pool:

determine whether a connector/app is code-backed, published, installed, connected,
pending, degraded, or unavailable;
expose only capabilities whose connector/application prerequisites are satisfied;
route activation to Marketplace Installation and Integration Manager;
keep raw credentials behind Provider Management/Integration Manager.

The marketplace UI is a discovery surface. It is not the capability execution engine.

4.5 Plugin and MCP marketplace applications

Sources/services:

IW-Spine-Network Plugin/MCP publication contract;
MARKETPLACE_INSTALLATION runtime;
host installation and consent records;
delegated capability bindings recorded in the Spine Network.

Responsibilities in the Pool:

check that the host/plugin installation is active and consented;
resolve the installation to the correct tenant/workspace/Spine Network;
include channel and installation lineage in audit metadata;
permit only declared IW semantic capabilities;
reject credential inheritance or unrestricted host-app discovery.

The Pool does not execute marketplace UI code and does not ingest arbitrary host tools.

4.6 Twin Orchestrator, Intelligence, and Agent Runtime

Bindings:

TWIN_ORCHESTRATOR
INTELLIGENCE
AGENT_RUNTIME

Responsibilities:

observe, reason, propose, and coordinate;
resolve contextual Twin requests;
prepare immutable action plans;
invoke user-facing agent runtime only with authenticated actor and tenant authority;
never execute operational writes without governance.

Twin Orchestrator is cognitive orchestration. Intelligence is the consolidated
think/act/govern runtime. Agent Runtime owns user-facing Twin/agent sessions and Durable
Object state. They are separate runtime adapters, not interchangeable aliases.

4.7 Agent and execution logs

Sources:

Twin/agent session logger;
invocation audit envelope;
task/workflow execution history;
Cloudflare observability.

Every Pool invocation records or emits:

correlation id;
tenant, workspace, user, role, and installation lineage;
public semantic tool and resolved internal capability;
selected runtime and implementation version;
policy and approval decision;
input hash/redaction metadata;
outcome status, duration, retry/fallback state, and evidence refs.

The Pool must not store private chain-of-thought. Logs contain decisions, actions,
evidence, errors, and performance metadata only.

4.8 Memory, Knowledge, Continuity, and promotion queues

Bindings/resources:

KNOWLEDGE
CONTINUITY
MEMORY_PROMOTE queue
KNOWLEDGE_QUEUE where applicable
Pipeline promotion consumer

Responsibilities:

retrieve permitted conversational and organisational memory;
query governed knowledge;
propose memory with evidence and lineage;
publish eligible Spine write events to MEMORY_PROMOTE;
let Pipeline's promotion engine score the seven promotion signals;
stage approval-required memory;
promote approved memory and index it;
record memory-promotion audit rows.

The Pool does not write org_memory directly and does not bypass the promotion or
approval lifecycle.

4.9 Task and Workflow runtimes

Bindings:

TASK_MANAGEMENT
WORKFLOW

Responsibilities:

scheduled and condition-driven task lifecycle;
deferred execution;
retries, cancellation, DLQ, metrics, and execution history;
governed workflow start and result reconciliation.

5. Required Pool binding model

Hard readiness dependencies

The Pool is not ready without:

Operational Spine context/state;
ADK registry/resolver;
Pipeline write/reconciliation path;
Integration Manager;
Provider Manager;
Knowledge/Continuity read path;
audit/event sink.

Capability-scoped dependencies

The Pool remains generally ready but marks capabilities degraded/unavailable when these
are absent:

Marketplace Installation;
Twin Orchestrator;
Agent Runtime;
Task Management;
Workflow;
optional connector/provider runtimes.

Readiness is therefore two-dimensional:

control-plane readiness — can the Pool resolve authority and policy safely?
capability readiness — is a specific implementation available and healthy?

6. Invocation lifecycle

1. MCP Connector authenticates actor and maps one of 19 public tools to intent.
2. Pool loads tenant/workspace/installation context from Operational Spine fabric.
3. ADK resolves stable capability eligibility and target class.
4. Marketplace and connector state qualify the capability for this workspace.
5. Governance determines read, proposal, approval, or forbidden mode.
6. Agent registry/version resolver selects a healthy implementation.
7. Runtime adapter invokes service, queue, workflow, or agent runtime.
8. Pool records audit/execution metadata.
9. Result is normalized to evidence.
10. Operational outcomes reconcile through Pipeline into Spine.
11. Eligible Spine writes enter memory-promotion lifecycle.
12. MCP Connector returns bounded semantic output through the public 19-tool facade.

No denial falls back to a direct vendor call.

7. Explicitly rejected topology

The following topology is invalid:

Client
  +-> Cloudflare MCP
  +-> GitHub MCP
  +-> Google MCP
  +-> provider MCPs
  +-> local filesystem/playwright/memory processes
  +-> IW MCP

It bypasses the IntegrateWise trust boundary, fragments identity and audit, exposes raw
provider semantics, and prevents Operational Spine continuity.

The accepted topology is:

Client -> IW MCP -> MCP Pool -> governed capability fabric -> provider/runtime

8. Repository reconciliation findings

The following existing code must not remain canonical without correction:

packages/spine-network/README.md still advertises a local npx/stdio setup even
though the current distribution contract is remote MCP. Update it to remote-first and
move stdio to a clearly separate compatibility/operator profile or retire it.
services/gateway/src/ai-plugin-marketplace.ts contains a legacy hard-coded connector
list, direct Nango session creation, locally constructed tenant identities, and direct
token persistence. Replace this path with Gateway identity resolution + Marketplace
Installation + Integration Manager + credential wall.
services/marketplace-installation/wrangler.toml contains placeholder D1 ids. The
runtime is implemented but is not a production-ready hard dependency until real
bindings are provisioned and verified.
The projection-engine capability resolver is a presentation/readiness resolver and
contains connector-status logic drift. It must not replace the ADK execution resolver.
MCP Pool's current registrations list internal tool names but do not yet compose ADK,
marketplace eligibility, agent registry, audit, memory promotion, and runtime adapters.

9. Implementation sequence for PR #109

Add @integratewise/adk to MCP Pool and make ADK resolution mandatory.
Add Operational Spine tenant-context adapter using D1/KV or a dedicated Spine Fabric
service contract.
Add runtime adapter registry; stop assuming every downstream service uses /invoke.
Add bindings for Pipeline, Knowledge, Continuity, Intelligence, Twin Orchestrator,
Agent Runtime, Workflow, and Marketplace Installation.
Mark optional runtimes capability-degraded instead of failing the whole Pool.
Add marketplace/connector eligibility resolver from code catalog + Spine publication
state + installation/connection state.
Add audit event emission and agent/execution log correlation.
Add promotion queue publishing only after successful reconciled Spine writes.
Wire MCP Connector semantic actions to stable ADK capabilities.
Remove stale client fan-out and legacy plugin bypass paths.
Verify contract tests, package tests, Cloudflare bindings, and an authenticated E2E
read -> proposal -> approval -> execution -> Spine reconciliation -> memory promotion.