# Proposers - Lluis Gifre (CTTC) # Description Introduce a TeraFlowSDN Model Context Protocol (MCP) server as a first-class deployable TFS component. The component exposes selected controller northbound capabilities as MCP tools/resources so external automation agents can discover controller capabilities, query inventory, inspect topology and optical resources, and execute controlled service lifecycle actions through stable tool contracts. The MCP server must not duplicate controller state or bypass existing TFS authorization, validation, service, context, or optical-controller logic. Instead, it acts as a protocol adapter that translates MCP requests into existing TFS APIs and gRPC clients, returning compact structured responses suitable for agentic automation and troubleshooting. The initial focus is optical-domain automation: contexts, topologies, devices, packet links, optical links, services, connections, spectrum candidates/reservations, and optical service allocation verification. # Demo or definition of done The feature is complete when TeraFlowSDN can deploy the MCP server together with the controller stack using the normal deployment framework, configure it through Kubernetes manifests/Helm values or equivalent TFS deployment settings, and expose a standards-compliant MCP endpoint. A client must be able to discover the available MCP tools, retrieve controller inventory from the `admin` context/topology, list optical links, retrieve optical path/spectrum candidates, create and release optical spectrum reservations, verify effective optical service allocation, and perform the TFS two-step optical connectivity service lifecycle through existing TFS components. Unit and integration tests must demonstrate that MCP responses are consistent with TFS API/gRPC state and that mutating operations fail safely when controller validation rejects the request. ## Acknowledgements This work is partially supported by the European Union's Horizon Europe Research and Innovation Program under grant 101139134 in the PROTEUS-6G project. # References 1. [Model Context Protocol specification](https://modelcontextprotocol.io/) # Feature Design (for New-Features) ## Clarifications to Expected Behavior Changes TeraFlowSDN currently exposes northbound operations mainly through its existing NBI/API and internal gRPC clients. This feature adds an MCP server component that makes a curated subset of those operations discoverable and callable by MCP clients. The component must be a thin adapter: it must use existing TFS clients and service/component APIs and must not introduce a parallel inventory database, path computation engine, service orchestrator, or spectrum authority. Expected behavior changes: - A new deployable `mcp` or `mcpserver` component is available in TFS deployments. - The component exposes a configurable HTTP/SSE MCP endpoint. - The component discovers or registers a stable set of MCP tools/resources at startup. - Read-only tools return compact summaries by default and allow detailed outputs only when explicitly requested. - Mutating tools call existing TFS logic and preserve the existing TFS validation and failure semantics. - Tool names and schemas remain versioned and backward-compatible where possible. - Controller state remains authoritative; MCP responses must be derived from TFS Context, Service, PathComp, Optical, and NBI data. This is justified because agentic automation systems need a machine-discoverable tool interface with explicit schemas, while TFS should remain the source of truth and retain all controller-side validation. ## References - Model Context Protocol. - Existing TFS NBI `/tfs-api` resources. - Existing TFS Context, Service, PathComp, and Optical Controller gRPC clients. - Existing optical spectrum reservation and optical path/spectrum candidate features. ## Assumptions - Existing TFS context, topology, device, link, optical-link, service, connection, and optical-spectrum features are available. - Existing optical connectivity service creation follows the TFS two-step lifecycle: create/reserve service identity first, then update endpoints, constraints, and config rules. - Existing optical path/spectrum candidate and reservation APIs are available and remain the authoritative source for spectrum availability and holds. - The initial MCP endpoint can run without user-level multi-tenant authorization beyond the deployment's existing TFS access model. - The component is deployed inside the TFS Kubernetes environment and can reach the required TFS component services through cluster DNS. - TLS/authentication for external exposure can initially rely on the same deployment/ingress mechanisms used by other TFS northbound endpoints. ## Impacted Components - Deployment/Manifests - Common/Settings - Context - Service - PathComp - Optical Controller - NBI - Tests/CI - Documentation ## Deployment/Manifests Impact Add a new TFS component deployment for the MCP server, including container image, service, configurable port, environment variables, logging level, and optional ingress/service exposure. The deployment must be disabled by default if that is the TFS convention for optional northbound components, or enabled explicitly through a deployment flag. Configuration should include default context/topology values, bind address/port, allowed tool groups, TFS component endpoints, and optional authentication settings. ## Common/Settings Impact Add component settings for the MCP server following existing TFS configuration patterns. Settings should include: - MCP bind host and port. - Default context UUID/name, normally `admin`. - Default topology UUID/name, normally `admin`. - Enabled tool groups, for example `inventory`, `topology`, `service`, `optical`, `spectrum`. - Request timeout and response-size limits. - Log level. Shared response helpers may be added only for formatting or error handling; business logic must stay in the owning TFS components. ## Context Impact The MCP server should use Context APIs to read contexts, topologies, devices, packet links, optical links, services, connections, and reservations. No Context database schema change is expected for the MCP server itself. If a required resource is not exposed by Context clients, the missing exposure should be added to Context/NBI as a separate focused change rather than inferred inside the MCP component. ## Service Impact The MCP server should call the existing Service APIs for service create/update/delete/get/list operations. For optical connectivity services, MCP tools must preserve the TFS two-step lifecycle and return the final observed service state. The MCP component must not compute service paths or mark services successful without retrieving authoritative service state from TFS. ## PathComp Impact The MCP server may expose path candidate tools only by calling existing PathComp or NBI facade APIs. If path computation for optical connectivity is owned by the Optical Controller, the MCP tool should call the existing facade/API that delegates to the Optical Controller rather than implementing path logic locally. ## Optical Controller Impact The MCP server should expose optical-specific tools through existing Optical Controller/NBI functionality: - list optical links; - retrieve optical path/spectrum candidates; - reserve/commit/release spectrum holds; - retrieve effective spectrum allocation after service activation; - verify requested versus effective allocation. The Optical Controller remains responsible for optical path feasibility, spectrum requirements, and effective allocation decisions. The MCP server must not independently decide modulation compatibility, channel width, or slot occupancy beyond passing validated requests to the controller. ## NBI Impact NBI may be used as the facade for REST-style access to Context, Service, and Optical Controller operations. If some required controller operation is only exposed through internal gRPC clients, either the MCP component can use the same internal client directly or NBI can be extended with a facade endpoint. The preferred approach is to avoid duplicating NBI behavior in MCP while keeping the MCP tool contracts stable for automation clients. ## Tests/CI Impact Add unit tests for: - MCP tool registration and schema generation. - Context/topology/device/link/optical-link read tools. - Service lifecycle request validation and payload construction. - Error mapping from TFS exceptions/rejections to MCP tool errors. - Response compaction and detail-level behavior. Add integration tests for: - Starting the MCP component in a test deployment. - Discovering tools through an MCP client. - Reading the `admin` context/topology inventory. - Listing optical links and spectrum candidates. - Creating, updating, verifying, and deleting an optical connectivity service through MCP while confirming TFS API/gRPC state. - Rejecting conflicting spectrum reservations and verifying the controller remains consistent. ## Documentation Impact Document: - How to enable and configure the MCP component. - MCP endpoint URL and transport. - Tool groups and tool schemas. - Security and exposure recommendations. - Examples for inventory, optical-link listing, spectrum reservation, optical service creation, verification, and teardown.