{"slug":"architecture/MCP_POOL_MULTI_ENVIRONMENT_STRATEGY","title":"MCP Pool Multi-Environment Strategy","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/MCP_POOL_MULTI_ENVIRONMENT_STRATEGY.mdx","bytes":13242,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status**: DRAFT  \n**Date**: 2026-07-30  \n**Related**: PR #109 (Remote-Only MCP Architecture)\n\n---\n\n## Architecture Overview\n\nThe MCP Pool must handle three distinct operational profiles while maintaining the frozen remote-only architecture:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                   IntegrateWise MCP Fabric                  │\n├─────────────────────────────────────────────────────────────┤\n│                                                             │\n│  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────┐│\n│  │  Customer Zero   │  │   Development    │  │   External   ││\n│  │   MCP Pool       │  │   MCP Pool       │  │   MCP Pool   ││\n│  │                  │  │                  │  │             ││\n│  │  Full Spine      │  │  Full Spine      │  │  Subset      ││\n│  │  Full ADK        │  │  Full ADK        │  │  Capabilities││\n│  │  All MCPs        │  │  All MCPs        │  │  Selected    ││\n│  │  Internal-only   │  │  Internal-only   │  │  Public      ││\n│  └──────────────────┘  └──────────────────┘  └─────────────┘│\n│           │                    │                    │        │\n│           ▼                    ▼                    ▼        │\n│  ┌────────────────────────────────────────────────────────┐│\n│  │              Internal MCP Services                     ││\n│  │  Provider Management · Integration Management          ││\n│  │  Task Management · Spine (Neon + D1)                 ││\n│  └────────────────────────────────────────────────────────┘│\n│                                                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Three MCP Pool Profiles\n\n### 1. Customer Zero MCP Pool (`mcp-pool-customer-zero`)\n\n**Purpose**: Internal platform development and operations  \n**Environment**: Production isolation  \n**Access**: Internal only via `iw-customer-zero` tenant\n\n**Characteristics**:\n\n- Full operational spine fabric integration\n- All internal MCP services (Provider, Integration, Task, Spine)\n- Complete ADK capability resolution\n- Direct Neon workbench access\n- Full memory and continuity integration\n- Complete marketplace connector access\n\n**Service Bindings**:\n\n```toml\n[[services]]\nbinding = \"PROVIDER_MANAGEMENT\"\nservice = \"integratewise-provider-management-mcp-prod\"\n\n[[services]]\nbinding = \"INTEGRATION_MANAGEMENT\"\nservice = \"integratewise-integration-management-mcp-prod\"\n\n[[services]]\nbinding = \"TASK_MANAGEMENT\"\nservice = \"integratewise-task-management-prod\"\n\n[[services]]\nbinding = \"SPINE\"\nservice = \"integratewise-spine-prod\"\n```\n\n**Allowed Tenants**: `[\"iw-customer-zero\"]`  \n**Deployment**: Cloudflare Workers prod environment  \n**Resources**: Isolated D1, KV, Vectorize per environment\n\n---\n\n### 2. Development MCP Pool (`mcp-pool-dev`)\n\n**Purpose**: Parallel development environment  \n**Environment**: Development isolation  \n**Access**: Internal development teams\n\n**Characteristics**:\n\n- Full operational spine fabric (development copies)\n- All internal MCP services (dev versions)\n- Complete ADK capability resolution\n- Development Neon workbench access\n- Full memory and continuity integration\n- Complete marketplace connector access\n- Hot-reload and debugging capabilities\n\n**Service Bindings**:\n\n```toml\n[[services]]\nbinding = \"PROVIDER_MANAGEMENT\"\nservice = \"integratewise-provider-management-mcp-dev\"\n\n[[services]]\nbinding = \"INTEGRATION_MANAGEMENT\"\nservice = \"integratewise-integration-management-mcp-dev\"\n\n[[services]]\nbinding = \"TASK_MANAGEMENT\"\nservice = \"integratewise-task-management-dev\"\n\n[[services]]\nbinding = \"SPINE\"\nservice = \"integratewise-spine-dev\"\n```\n\n**Allowed Tenants**: `[\"iw-dev\"]`  \n**Deployment**: Cloudflare Workers dev environment  \n**Resources**: Isolated D1, KV, Vectorize per environment\n\n---\n\n### 3. External MCP Pool (`mcp-pool-external`)\n\n**Purpose**: Public-facing capabilities with governance boundaries  \n**Environment**: Production isolation  \n**Access**: External customers via marketplace connectors\n\n**Characteristics**:\n\n- **Subset of capabilities** (19-tool semantic contract)\n- **Selected internal MCP services** only\n- **Capability filtering** based on customer tier\n- **No direct Spine access** (via gateway only)\n- **No internal memory access** (customer-scoped only)\n- **Marketplace connector integration**\n- **Governance enforcement** per customer\n\n**Service Bindings**:\n\n```toml\n[[services]]\nbinding = \"INTEGRATION_MANAGEMENT\"\nservice = \"integratewise-integration-management-mcp-prod\"\n\n[[services]]\nbinding = \"TASK_MANAGEMENT\"\nservice = \"integratewise-task-management-prod\"\n\n# NO PROVIDER_MANAGEMENT (external customers cannot manage providers)\n# NO SPINE (external customers access via gateway API only)\n```\n\n**Allowed Tenants**: `[\"external-*\"]` (wildcard for external customers)  \n**Deployment**: Cloudflare Workers prod environment  \n**Resources**: Isolated D1, KV, Vectorize per environment\n\n---\n\n## Capability Exposure Matrix\n\n| Capability             | Customer Zero | Development | External           |\n| ---------------------- | ------------- | ----------- | ------------------ |\n| Provider Management    | ✅ Full       | ✅ Full     | ❌ None            |\n| Integration Management | ✅ Full       | ✅ Full     | ✅ Filtered        |\n| Task Management        | ✅ Full       | ✅ Full     | ✅ Filtered        |\n| Spine CRUD             | ✅ Full       | ✅ Full     | ❌ Gateway Only    |\n| Memory Access          | ✅ Full       | ✅ Full     | ✅ Customer-Scoped |\n| Marketplace Connectors | ✅ All        | ✅ All      | ✅ Purchased       |\n| ADK Resolution         | ✅ Full       | ✅ Full     | ✅ Filtered        |\n| Internal MCPs          | ✅ All        | ✅ All      | ✅ Selected        |\n\n---\n\n## Deployment Architecture\n\n### Cloudflare Workers Configuration\n\n**Three separate worker deployments**:\n\n```\nintegratewise-mcp-pool-customer-zero (prod)\nintegratewise-mcp-pool-dev (dev)\nintegratewise-mcp-pool-external (prod)\n```\n\n### Isolation Strategy\n\n**Each MCP Pool has its own**:\n\n- D1 databases (separate per environment)\n- KV namespaces (separate per environment)\n- Vectorize indexes (separate per environment)\n- Service bindings (different target services)\n- Tenant access policies (different allowed tenants)\n\n### Service Binding Strategy\n\n**Customer Zero** → Prod internal services  \n**Development** → Dev internal services  \n**External** → Prod services (filtered) + Gateway API\n\n---\n\n## Routing Strategy\n\n### Ingress Routing\n\n**Client Configuration** (Codex config.toml):\n\n```toml\n# Customer Zero\n[mcp_servers.iw-mcp]\nurl = \"https://mcp.integratewise.ai\"\nenabled = true\nrequired = true\n\n# Development (optional override)\n[mcp_servers.iw-mcp-dev]\nurl = \"https://mcp-dev.integratewise.ai\"\nenabled = false  # Disabled by default\n\n# External (marketplace connectors)\n[mcp_servers.iw-mcp-external]\nurl = \"https://mcp-external.integratewise.ai\"\nenabled = false  # Enabled via marketplace\n```\n\n### Tenant-Based Routing\n\n**MCP Connector** routes requests based on tenant:\n\n```typescript\nfunction routeToMCPPool(tenantId: string): string {\n  if (tenantId === \"iw-customer-zero\") {\n    return \"mcp-pool-customer-zero\";\n  }\n  if (tenantId.startsWith(\"iw-dev\")) {\n    return \"mcp-pool-dev\";\n  }\n  if (tenantId.startsWith(\"external-\")) {\n    return \"mcp-pool-external\";\n  }\n  return \"mcp-pool-external\"; // Default for external customers\n}\n```\n\n---\n\n## Governance Integration\n\n### Customer Zero Governance\n\n- Full internal governance policies\n- No capability restrictions\n- Direct approval workflows\n\n### Development Governance\n\n- Internal development governance\n- Test capability restrictions\n- Debug and monitoring capabilities\n\n### External Governance\n\n- Customer tier-based capability restrictions\n- Per-customer approval workflows\n- Usage-based capability limits\n- Audit and compliance requirements\n\n---\n\n## Resource Requirements\n\n### Customer Zero MCP Pool\n\n- D1: `mcp-pool-customer-zero-registry`\n- KV: `mcp-pool-customer-zero-cache`\n- Vectorize: `mcp-pool-customer-zero-index`\n\n### Development MCP Pool\n\n- D1: `mcp-pool-dev-registry`\n- KV: `mcp-pool-dev-cache`\n- Vectorize: `mcp-pool-dev-index`\n\n### External MCP Pool\n\n- D1: `mcp-pool-external-registry`\n- KV: `mcp-pool-external-cache`\n- Vectorize: `mcp-pool-external-index`\n\n---\n\n## Implementation Steps\n\n### Phase 1: Customer Zero (Current)\n\n- ✅ Complete PR #109 (remote-only architecture)\n- ⏳ Deploy isolated MCP Pool for Customer Zero\n- ⏳ Update Codex config for Customer Zero\n- ⏳ Test full operational spine integration\n\n### Phase 2: Development Environment\n\n- ⏳ Create dev MCP Pool deployment\n- ⏳ Set up dev service bindings\n- ⏳ Configure development Codex profiles\n- ⏳ Test development workflow\n\n### Phase 3: External Profile\n\n- ⏳ Create external MCP Pool deployment\n- ⏳ Implement capability filtering\n- ⏳ Integrate with marketplace\n- ⏳ Test external customer access\n\n---\n\n## Security Considerations\n\n### Isolation Requirements\n\n- **No resource sharing** between MCP Pools\n- **Tenant-based routing** enforced at MCP Connector\n- **Capability filtering** for external pool\n- **Internal-only services** protected from external access\n\n### Data Protection\n\n- **Customer Zero**: Full internal data access\n- **Development**: Development data isolation\n- **External**: Customer-scoped data only, no internal access\n\n### Access Control\n\n- **Tenant allowlists** per MCP Pool\n- **Service binding validation** at startup\n- **Runtime capability checks** on each invocation\n- **Audit logging** for all external access\n\n---\n\n## Monitoring and Observability\n\n### Metrics per MCP Pool\n\n- Invocation counts per capability\n- Success/failure rates by tenant\n- Latency metrics by service binding\n- Resource utilization (D1, KV, Vectorize)\n\n### Logging Strategy\n\n- **Customer Zero**: Full debug logging\n- **Development**: Enhanced logging for debugging\n- **External**: Security-focused logging, customer isolation\n\n---\n\n## Compliance and Auditing\n\n### Customer Zero\n\n- Internal audit trail\n- Full capability access logging\n- No external compliance requirements\n\n### Development\n\n- Development activity logging\n- Change tracking and rollback\n- No external compliance requirements\n\n### External\n\n- Per-customer audit trails\n- Capability access logging\n- GDPR/SOC2 compliance requirements\n- Data retention policies\n\n---\n\n## Cost Optimization\n\n### Resource Scaling\n\n- **Customer Zero**: High-performance, full resources\n- **Development**: Variable resources, auto-scale\n- **External**: Tiered resources based on customer plan\n\n### Usage-Based Allocation\n\n- External customers pay for capability usage\n- Development environment cost allocation\n- Customer Zero internal cost center\n\n---\n\n## Migration Strategy\n\n### From Current Architecture\n\n1. Deploy Customer Zero MCP Pool (isolated)\n2. Update Codex configuration for Customer Zero\n3. Deploy Development MCP Pool\n4. Implement external MCP Pool with filtering\n5. Update MCP Connector routing logic\n6. Deprecate old shared MCP Pool\n\n### Rollback Plan\n\n- Keep old MCP Pool available during transition\n- Per-tenant routing with fallback\n- Gradual migration of customer base\n- Final removal of old pool after validation\n\n---\n\n## Success Criteria\n\n### Customer Zero MCP Pool\n\n- ✅ Remote-only architecture (no local MCP processes)\n- ✅ Full operational spine integration\n- ✅ All internal MCP services connected\n- ✅ Resource isolation verified\n- ✅ Zero violations in audit script\n\n### Development MCP Pool\n\n- ✅ Complete development environment parity\n- ✅ Hot-reload and debugging capabilities\n- ✅ Development resource isolation\n- ✅ No interference with production\n\n### External MCP Pool\n\n- ✅ Capability filtering working correctly\n- ✅ Tenant-based routing functioning\n- ✅ No internal data exposure\n- ✅ Marketplace integration complete\n- ✅ Compliance requirements met\n\n---\n\n**Related Documents**:\n\n- [PR #109 - Remote-Only MCP Architecture](../../pull/109)\n- [Resource Isolation Audit](../operations/RESOURCE_ISOLATION_AUDIT.md)\n- [Architecture Lock](../architecture/ARCHITECTURE_LOCK.md)\n- [Customer Zero Spec](../architecture/CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md)\n"}