System Capability Protocol (SCP)

A machine-first system architecture description protocol enabling LLMs, observability tooling, and alerting systems to reason about distributed systems.

What is SCP?

SCP provides a declarative manifest format (scp.yaml) that describes what a system should be.

Is this like MCP or OpenAPI?

No, SCP is different from MCP and OpenAPI. SCP is a machine-first system architecture description protocol. MCP - Tells a LLM how it can use a system to perform an action or task. OpenAPI - Describes an implementation.

SCP does the following:

1. For an LLM it tells the model what a system is and how it is interconnected, for smarter troubleshooting and change impact analysis.
2. For observability tooling it provides a system map, that could be compared to a map generated from, for example, OpenTelemetry traces. This allows for theory (developer view) vs reality (runtime view) analysis ensuring that how we think systems are interconnected matches what is actually happening.
3. For alerting it provides ownership and blast radius information, and potentially the ability to automate the updating of alerts. For example if service A depends on service B, and service B is down, then alert on service A and ignore service B.
4. Using the tooling it provides a system map, that can be used for autogenerated documentation and helping Ops teams understand where systems are interconnected.

# scp.yaml
scp: "0.1.0"

system:
  urn: "urn:scp:acme:payment-service"
  name: "Payment Service"
  classification:
    tier: 1
    domain: "payments"

ownership:
  team: "payments-platform"

provides:
  - capability: "payment-processing"
    type: "rest"
    contract:
      type: "openapi"
      ref: "./api/openapi.yaml"

depends:
  - system: "urn:scp:acme:user-service"
    type: "rest"
    criticality: "required"
    failure_mode: "fail-fast"

runtime:
  environments:
    production:
      otel_service_name: "payment-service"

Key Features

• LLM Reasoning: Enables change impact analysis and migration planning
• Architecture Discovery: Scan repos to generate org-wide system maps
• Theory vs Reality: Diff declared dependencies against OTel traces
• Smart Alerting: Auto-enrich alerts with ownership and blast radius
• Security Automation: SOAR autodiscovery via x-security extensions and OpenC2 export

Quick Start

1. Create scp.yaml

Add a manifest to your repository root. See spec/scp-v0.1.md for all fields.

2. Validate

# Requires: uv tool install check-jsonschema
make validate

3. Build Graph

Parse all scp.yaml files to build an org-wide dependency graph.

Design Principles

Principle	Description
Machine-first	Schemas over prose, deterministic parsing
Minimal v0	Essential fields only, avoid over-engineering
Composable	Works alongside OpenAPI, AsyncAPI, OTel
Late-bound	Supports partial adoption
Reality-aware	Join points with observability data

Related Projects

Project	Description
scp-integrations	CLI tooling to scan, validate, and export SCP graphs
scp-viewer	Interactive web dashboard for visualizing SCP architecture
scp-demo	Example 3-tier application with SCP manifests
scp-sdk	SDK to assist with building integrations

Documentation

• Specification - Complete manifest format
• Graph Model - Neo4j schema and queries

License

MIT