Project Configuration

You can add a .scc.yaml file to your repository root to customize SCC settings for that specific project.

When to Use Project Config

Use .scc.yaml when you need:

• Project-specific plugins
• Project-specific MCP servers
• Custom session timeouts (auto_resume is advisory)

Note

Project configuration extends your team config. You cannot override organization security blocks or remove team defaults.

File Location

• Directorymy-project/

  • .scc.yaml ← Project config
  • Directory.git/

    • …
  • Directorysrc/

    • …
  • package.json

Basic Structure

.scc.yaml

# Add plugins specific to this project
additional_plugins:
  - "eslint-plugin@internal"
  - "project-linter@team-marketplace"

# Optional MCP servers for this project
additional_mcp_servers:
  - name: "project-api"
    type: "sse"
    url: "https://api.example.com/mcp"

# Override session settings
session:
  timeout_hours: 4

Note

.scc.yaml does not select a team. Use scc team switch or scc start --team.

Available Options

Additional Plugins

Add plugins beyond what your team provides:

additional_plugins:
  - "plugin-name@marketplace"
  - "another-plugin@marketplace"

Caution

You can only add plugins that match defaults.allowed_plugins (if set) and pass org security blocks. Attempts to add disallowed plugins will be blocked.

Session Settings

Override session behavior:

session:
  timeout_hours: 4      # Override team default
  auto_resume: false    # Advisory only in v1

Note

session.auto_resume is accepted but advisory in v1. It is not enforced at runtime.

Additional MCP Servers

Add MCP servers scoped to this project:

additional_mcp_servers:
  - name: project-api
    type: sse
    url: https://api.example.com/mcp

Note

MCP servers must pass org security blocks and defaults.allowed_mcp_servers (if set). Plugin-bundled MCP servers are not inspected.

Example Configurations

Monorepo Frontend Package

.scc.yaml

# Add React-specific tooling
additional_plugins:
  - "react-tools@frontend-marketplace"

session:
  timeout_hours: 8

Security-Sensitive Project

.scc.yaml

# Short sessions for sensitive work
session:
  timeout_hours: 2
  auto_resume: false

Data Science Project

.scc.yaml

# Longer sessions for training runs
session:
  timeout_hours: 24

# Add data science plugins
additional_plugins:
  - "jupyter-helper@ml-marketplace"
  - "pandas-tools@ml-marketplace"

Validation

Validate your project config:

scc config validate

This checks:

• YAML syntax is correct
• Referenced plugins/MCP servers are allowed
• Project delegation rules are satisfied
• Selected team exists in org config
• Unknown keys are reported (ignored at runtime)

Note

Validation uses your current team (set via scc team switch) unless you pass --team.

Seeing Effective Config

To see how project config combines with team and org settings:

scc config explain

Output shows the source of each setting:

Effective configuration for ~/project:

plugins:
  - scc-safety-net        (from: team/backend)
  - code-formatter        (from: team/backend)
  - eslint-plugin         (from: project/.scc.yaml)  ← Project addition

session:
  timeout_hours: 4        (from: project/.scc.yaml)  ← Project override
  auto_resume: true       (from: team/backend, advisory)

network_policy: corp-proxy-only (from: org/defaults)

What You Cannot Override

Project config cannot:

• Remove team default plugins
• Unblock organization-blocked plugins
• Override network policy (projects cannot set it; teams can only tighten org defaults)
• Bypass security settings

Danger

Organization security blocks are absolute. Even if you try to add a blocked plugin in .scc.yaml, it will be filtered out.

Git Ignore Considerations

The .scc.yaml file should typically be committed to your repository so all team members get the same project settings.

Local-only overrides are not supported in v1. Use personal profiles for machine-specific plugins or MCP servers.

Personal Profiles (Local)

If you want your own plugins or MCP servers without committing anything to the repo, use personal profiles.

scc profile save
scc profile apply

Personal profiles live outside the repo and can be synced across machines. See Personal Profiles for details.

Note

When SCC applies a profile, it enforces org security blocks and stdio MCP gating. Manual edits to local workspace files are advisory.

Troubleshooting

”Plugin not allowed”

Your team’s delegation rules don’t permit that plugin. Check with your team lead.

scc config explain --field denied

”Team not found”

Your selected team no longer exists in the org config. Pick a valid team:

scc team list
scc team switch <team>

Changes not taking effect

Project config is read at session start. Restart your session:

scc stop
scc start --fresh