Project Schema

Schema reference for project-level configuration (.scc.yaml).

Location

Place .scc.yaml in your repository root:

my-project/
├── .scc.yaml
├── src/
└── ...

Requirements

For project additions and session overrides in .scc.yaml to take effect:

Org enables project delegation (delegation.projects.inherit_team_delegation: true)
Team has delegation.allow_project_overrides: true
Resources must not match security blocks
Plugins must match defaults.allowed_plugins (if specified)

Project network_policy is different from plugin and MCP additions: it can only tighten the effective org/team policy. Looser team or project values are ignored and reported as “Ignored Policy Changes”.

Top-Level Structure

additional_plugins: []
additional_mcp_servers: []
network_policy: web-egress-enforced
dev_environment:
  commands: {}
session: {}

additional_plugins

Plugins to add for this project.

additional_plugins:
  - project-linter@internal
  - react-tools@claude-plugins-official

Requirements:

Team must allow project overrides
Plugin must match defaults.allowed_plugins patterns
Plugin must not match org’s blocked_plugins

additional_mcp_servers

MCP servers for this project.

If type is omitted, SCC treats the server as sse. Network MCP servers (http or sse) are blocked when the effective network_policy is locked-down-web.

additional_mcp_servers:
  - name: project-api
    type: http
    url: https://api.myproject.com/mcp

HTTP/SSE Server

additional_mcp_servers:
  - name: context7
    type: sse
    url: https://context7.com/api
    headers:
      Authorization: "Bearer ${CONTEXT7_TOKEN}"

Stdio Server

additional_mcp_servers:
  - name: local-tool
    type: stdio
    command: /usr/local/bin/tool
    args:
      - --config
      - ./tool.conf

Requires:

Org to set security.allow_stdio_mcp: true
Command path to match security.allowed_stdio_prefixes
MCP server must match defaults.allowed_mcp_servers (if specified)

network_policy

Optional project-level network restriction.

network_policy: locked-down-web

Allowed values:

open
web-egress-enforced
locked-down-web

Projects can only keep or tighten the effective org/team policy. For example, a project can change open to web-egress-enforced or locked-down-web, but a project cannot change locked-down-web to open.

Unknown project values fail project-config validation. Looser values are ignored and appear in scc config explain --field network under “Ignored Policy Changes”.

dev_environment bridge actions

Optional named project-support actions for devcontainer or Compose projects. SCC supports dev_environment.commands, dev_environment.logs, and dev_environment.health_checks. Each action must be a map with a non-empty fixed argv list:

dev_environment:
  commands:
    test:
      argv: ["uv", "run", "pytest", "-q"]
      working_directory: "."
      timeout_seconds: 120
      description: "Run the project test suite"
  logs:
    api:
      argv: ["docker", "compose", "logs", "--tail", "100", "api"]
      timeout_seconds: 30
      description: "Read recent API logs"
  health_checks:
    api:
      argv: ["curl", "-fsS", "http://localhost:8000/health"]
      timeout_seconds: 10
      description: "Check local API health"

Requirements:

org enables project delegation with delegation.projects.inherit_team_delegation: true;
team has delegation.allow_project_overrides: true;
org delegation.teams.allow_dev_environment_commands matches the selected team;
action names must be non-empty strings within their section;
argv must be a non-empty list of non-empty strings.

SCC rejects shell strings such as argv: "uv run pytest -q". Use:

scc config explain --field dev_environment
scc config explain --json
scc dev status . --json
scc dev run test .
scc dev logs api .
scc dev health api .

to inspect or execute accepted actions. scc dev run <name>, scc dev logs <name>, and scc dev health <name> write a pre-execution audit event before launching the host process, reject unknown names, reject working_directory values that escape the workspace after symlink resolution, and return bounded stdout/stderr tails.

session

Session settings for this project.

session:
  timeout_hours: 8
  auto_resume: false

Project session settings override team settings.

Notes

Unknown keys are ignored; scc config validate will warn.
.scc.yaml does not set team selection or entry directories.

Complete Example

additional_plugins:
  - project-linter@internal
  - react-devtools@claude-plugins-official
  - team-formatter@internal

additional_mcp_servers:
  - name: project-api
    type: http
    url: https://api.myproject.com/mcp
  - name: local-analyzer
    type: stdio
    command: /opt/tools/analyzer
    args:
      - --project
      - .

session:
  timeout_hours: 8
  auto_resume: true

network_policy: locked-down-web

dev_environment:
  commands:
    test:
      argv: ["uv", "run", "pytest", "-q"]
      working_directory: "."
      timeout_seconds: 120
      description: "Run the project test suite"

Validation

Validate your project config:

# In the project directory
scc config validate

# Inspect denied additions
scc config explain --field denied

Common Issues

”Team disallows project overrides”

Run:

scc config explain --field denied

Look for a “Denied Additions” entry with reason team '<team>' disabled project overrides.

”Plugin doesn’t match allowed patterns”

Run:

scc config explain --field denied

Look for a “Denied Additions” entry with reason Plugin not allowed by defaults.allowed_plugins.

”Blocked by security policy”

Run:

scc config explain --field blocked

Look for a “Blocked Items” entry showing the security.blocked_plugins pattern.

”Network policy ignored”

Run:

scc config explain --field network

Look for an “Ignored Policy Changes” entry. Teams and projects can only keep or tighten the inherited network_policy.