MCPO2

MCPO2 is a policy-aware MCP routing and access fabric for agents and developers. It sits between clients and approved remote MCP-style modules, classifies task intent, applies tenant and capability policy, injects controlled execution preambles, handles large file and large context workloads, and returns normalized, audit-ready results.

This repository is the launch-stage foundation for that platform. It is not a generic proxy and it is not a local-repository automation tool. MCPO2 exists to make remote tool access governable.

Why This Exists

Direct access to remote tool endpoints creates the wrong control model for serious multi-tenant systems:

• callers can discover or target endpoints that should stay hidden
• policy and approval logic gets scattered across clients
• system instructions and tool access are hard to govern consistently
• large repositories and file sets are pushed through the wrong interfaces
• route decisions and execution evidence become difficult to audit

MCPO2 centralizes those concerns into a single execution fabric. Clients ask for work. MCPO2 decides whether the request is allowed, which capability family it belongs to, which registered module may handle it, which preamble profile must apply, and how file or context material should be referenced safely.

Core Product Concepts

• Policy-aware routing: requests are classified, evaluated, and routed through policy rather than direct endpoint discovery.
• Capability families: security, design, and engineering are first-class execution families with separate policy and routing semantics.
• Controlled preamble injection: the platform, not the caller, selects the system preamble profile used for execution.
• Remote MCP access: modules are registered and approved in the control plane; clients never call raw MCP endpoints directly.
• Large-context execution: large files and repository trees are handled through manifests, excerpts, and signed references instead of prompt bloat.
• Auditability: policy decisions, route choices, file references, and execution outcomes are preserved as structured evidence.

Current Repository Baseline

The current codebase implements three deployable backend services:

• control-plane-api
• execution-orchestrator
• artifact-service

Within those services, the repository already includes real foundations for:

• tenant, user, API key, role, and policy models
• capability and MCP module registry management
• request intake and execution planning
• rule-based classification and explainable routing
• controlled preamble resolution
• remote HTTP and streaming MCP adapter support
• large file ingest, manifest building, and selective context preparation
• audit history, quota controls, metrics, and tracing hooks
• Docker, Compose, and Kubernetes starter deployment assets

The repository also includes planned decomposition boundaries for future standalone services such as edge-gateway, policy-service, execution-router, audit-service, and family-specific gateways. Those directories are architectural targets, not fully deployed services in v0.1.0.

Architecture Summary

MCPO2 is organized around three active planes and one future edge boundary:

• Control plane: registry, policy, identity, tenancy, inspection, and administrative APIs
• Execution plane: request intake, classification, routing, preamble application, remote dispatch, and normalized responses
• Data plane: file ingest, manifest construction, brokered access, and execution payload preparation
• Edge boundary: a future dedicated ingress layer for public authentication, coarse admission, and transport termination

Current repository interaction:

1. Clients call execution-orchestrator for execution and artifact-service for large-file workflows.
2. execution-orchestrator classifies the request and asks control-plane-api for the policy decision.
3. The router shortlist is built from approved registry records and execution preferences.
4. The runtime dispatches only to approved remote MCP endpoints using normalized adapter contracts.
5. Audit evidence, quotas, and observability signals are recorded across the request path.

See ARCHITECTURE.md for the full model and diagrams.

Repository Structure

mcpo2/
|- .github/
|- cmd/
|  \- mcpo2ctl/
|- contracts/
|  |- openapi/
|  |- proto/
|  \- events/
|- docs/
|  |- github/
|  \- releases/
|- packages/
|- platform/
|  |- kubernetes/
|  |- helm/
|  \- terraform/
|- policies/
|- services/
|  |- control-plane-api/
|  |- execution-orchestrator/
|  |- artifact-service/
|  \- ...
|- README.md
|- ARCHITECTURE.md
|- ROADMAP.md
|- POLICY_MODEL.md
|- CAPABILITY_REGISTRY.md
|- REQUEST_LIFECYCLE.md
|- DATA_PLANE.md
|- MCP_ADAPTERS.md
|- AUDIT_MODEL.md
|- DEPLOYMENT.md
|- LOCAL_DEVELOPMENT.md
|- SECURITY_OPERATIONS.md
\- PUBLICATION_CHECKLIST.md

Development Status

This repository should be read as a serious systems foundation, not as a finished hosted product.

Implemented in the current snapshot:

• control plane foundation with registry, identity, policy, and inspection APIs
• execution orchestrator with classification, policy lookup, routing, preamble handling, streaming, and remote runtime dispatch
• data plane foundation with artifact ingest, manifests, signed access, and payload preparation
• audit, quotas, metrics, tracing hooks, startup checks, probes, and deployment assets
• CLI skeleton for operator and developer workflows

Not yet complete for a hardened public SaaS launch:

• dedicated edge gateway and public auth layer
• externalized policy bundles and full OPA runtime integration
• cloud object-storage adapter beyond local filesystem mode
• standalone family gateways and broader transport matrix
• service-to-service identity and stronger secret rotation automation

Roadmap Summary

The roadmap is organized around five product phases:

1. Foundation: contracts, control-plane models, runtime boundaries, and baseline deployment assets
2. Routing: request intake, classification, explainable routing, and execution planning
3. Data Plane: file ingest, manifests, selective context, and brokered references
4. Policy Engine: authoritative policy, capability constraints, preamble profiles, and approval controls
5. Production Hardening: audit, quotas, observability, secrets, deployment, and operational readiness

The current repository contains a baseline slice across all five phases. The remaining work is now about decomposition, hardening, and cloud-grade operations rather than starting from zero.

See ROADMAP.md for details.

Future Vision

MCPO2 is intended to become a secure access layer for remote MCP ecosystems:

• multi-tenant by default
• capability-scoped rather than endpoint-scoped
• region and trust-tier aware
• large-context native
• auditable enough for platform, security, and enterprise environments

The long-term shape is a dedicated execution fabric that lets platform teams approve remote tool access without handing raw endpoint topology, credentials, or unconstrained execution behavior to every client.

Documentation

Product And Architecture

• ARCHITECTURE.md
• ROADMAP.md
• POLICY_MODEL.md
• CAPABILITY_REGISTRY.md
• REQUEST_LIFECYCLE.md
• DATA_PLANE.md
• MCP_ADAPTERS.md
• AUDIT_MODEL.md

Deployment And Operations

• DEPLOYMENT.md
• LOCAL_DEVELOPMENT.md
• SECURITY_OPERATIONS.md
• ADMIN_API.md
• OBSERVABILITY.md
• QUOTAS_AND_LIMITS.md

Contribution And Publication

• CONTRIBUTING.md
• SECURITY.md
• docs/github/REPOSITORY_METADATA.md
• docs/releases/v0.1.0.md
• PUBLICATION_CHECKLIST.md

License

MCPO2 is released under the Apache 2.0 license. See LICENSE.