Claude Code settings.json Patterns for Mid-Market Engineering Teams
Master Claude Code settings.json patterns for mid-market teams. Permission modes, hooks, MCP servers, and audit-grade safety in regulated environments.
Table of Contents
- Why settings.json Matters for Mid-Market Teams
- Understanding the Configuration Hierarchy
- Permission Modes: Balancing Speed with Safety
- Hooks and Event Listeners for Audit-Ready Workflows
- MCP Servers: Extending Claude Code Capabilities
- Statusline Configuration for Team Visibility
- Real-World Patterns for Regulated Environments
- Implementation Roadmap for Your Team
- Common Pitfalls and How to Avoid Them
- Next Steps and Compliance Readiness
Why settings.json Matters for Mid-Market Teams
Mid-market engineering teams operate in a unique space. You’re large enough that you need governance, audit trails, and repeatable processes—but lean enough that you can’t afford the overhead of enterprise tooling that slows down shipping. Claude Code, when configured properly through settings.json, becomes the friction-reducing layer that lets you do both.
The problem most teams face: they treat Claude Code as a one-off productivity tool rather than a platform that needs to be governed. That works fine until you’re shipping to production, handling customer data, or prepping for SOC 2 compliance. Then suddenly you’re scrambling to understand what Claude did, who approved it, and whether it meets your security baseline.
A properly configured settings.json file solves this. It’s not a magic bullet—but it’s the difference between Claude Code being a liability and Claude Code being a force multiplier that your auditors actually respect.
At PADISO, we’ve helped Sydney-based and Australian mid-market teams configure Claude Code for everything from MVP shipping to production operations. The teams that move fastest are the ones with clear permission models, automated hooks that log decisions, and MCP server integrations that keep Claude in the right guardrails.
This guide walks you through the exact patterns we use with our clients.
Understanding the Configuration Hierarchy
Claude Code respects a three-tier configuration hierarchy. Understanding this hierarchy is non-negotiable—it’s where most teams get confused.
Global Settings vs. Project-Level Settings
Your global ~/.claude/settings.json file is your baseline. This lives in your home directory and applies to every Claude Code session unless overridden. Think of it as your organisation’s defaults: permission levels, which MCP servers are available globally, audit logging preferences.
Your project-level .claude/settings.json file lives in your repository root. This overrides global settings for a specific project. This is where you define project-specific constraints: maybe your payment processing module requires stricter permissions, or your data pipeline needs access to specific MCP servers.
Environment variables come third. They override both global and project settings, giving you runtime flexibility without touching config files. This is useful for CI/CD pipelines where you might want different permissions in staging versus production.
The Claude Code settings documentation outlines this hierarchy clearly. The key insight: most teams should define 70% of their policy at the global level, then use project-level overrides sparingly for high-risk modules.
Configuration Scope and Inheritance
When Claude Code initialises, it reads settings in this order:
- Global settings from
~/.claude/settings.json - Project settings from
.claude/settings.jsonin the repo root - Environment variables (if present)
Each level completely overrides the previous one for keys that are defined. If your global settings define "permissionMode": "strict" but your project settings define "permissionMode": "collaborative", the project setting wins.
This matters because it means you can’t rely on global settings to enforce policy. A developer can override your security baseline by committing a project-level settings file. That’s why we recommend storing your project-level settings in a protected branch and requiring code review for any changes to .claude/settings.json.
For teams pursuing SOC 2 compliance, this audit trail becomes critical. You need to track who changed what in your settings files and why.
Permission Modes: Balancing Speed with Safety
The permission mode is your most important setting. It defines what Claude Code can do without asking for approval.
The Four Permission Modes
Autonomous Mode ("permissionMode": "autonomous")
Claude Code executes file operations, runs commands, and makes changes without asking. This is fastest for MVP work and internal tooling. It’s also riskiest for regulated environments.
Use autonomous mode when:
- You’re building internal tools with no customer data
- Your team is small and co-located (easy to catch mistakes)
- You’re in early-stage startup mode where speed > safety
Don’t use it when:
- You’re handling PII or payment data
- You’re in a regulated industry (fintech, healthcare, legal)
- Your code touches production systems
Collaborative Mode ("permissionMode": "collaborative")
Claude Code asks for approval before executing file operations or running commands. This is the sweet spot for most mid-market teams. It adds minimal friction—maybe 10-15 seconds per operation—but creates a human checkpoint that auditors love.
Collaborative mode works because humans are still better at context. Claude might suggest a database migration that’s technically correct but operationally risky. A human reviewer catches that in seconds.
Implement collaborative mode with a clear approval workflow: one senior engineer approves changes, logs the decision, and moves on. Don’t make it a committee process or you’ll kill productivity.
Strict Mode ("permissionMode": "strict")
Claude Code can only read files and provide suggestions. It cannot execute anything. This is for high-risk modules: authentication systems, payment processing, compliance-critical workflows.
Strict mode is slower but safer. Use it for:
- Authentication and authorisation code
- Payment processing and financial calculations
- Data privacy and compliance-critical paths
- Security-sensitive infrastructure code
Interactive Mode ("permissionMode": "interactive")
Claude Code asks for permission for each operation, letting you review before execution. Similar to collaborative but more granular. Some teams use this as a training mode when engineers are new to Claude Code.
Mixing Modes Across Your Codebase
Here’s the pattern we recommend for mid-market teams: define your baseline permission mode globally (usually collaborative), then use project-level overrides for specific directories.
{
"permissionMode": "collaborative",
"directoryOverrides": {
"./src/auth": "strict",
"./src/payments": "strict",
"./src/data-pipelines": "strict",
"./internal-tools": "autonomous",
"./docs": "autonomous"
}
}
This approach gives you speed where it’s safe and caution where it matters. Your internal tooling ships fast. Your payment processing gets human eyes on every change. Your documentation updates happen automatically.
The Builder.io guide to Claude Code settings provides practical examples of this mixed-mode approach in action.
Hooks and Event Listeners for Audit-Ready Workflows
Hooks are where settings.json becomes powerful for compliance. Hooks are functions that fire when specific events happen—file creation, command execution, test failures. They’re your mechanism for creating audit trails without slowing down development.
Pre-Execution and Post-Execution Hooks
A pre-execution hook runs before Claude Code does something. It’s your last chance to veto an action. A post-execution hook runs after something happens. It’s your chance to log it, notify someone, or trigger downstream processes.
Here’s a practical example:
{
"hooks": {
"beforeFileWrite": {
"enabled": true,
"handler": "scripts/audit-file-write.js",
"logLevel": "info",
"timeout": 5000
},
"afterCommandExecution": {
"enabled": true,
"handler": "scripts/log-command-execution.js",
"logLevel": "info",
"timeout": 2000
},
"onTestFailure": {
"enabled": true,
"handler": "scripts/notify-test-failure.js",
"timeout": 3000
}
}
}
Your audit-file-write.js handler might check:
- Is this file in a protected directory?
- Does the change touch sensitive data structures?
- Does it match our coding standards?
If any check fails, the hook can reject the write. If it passes, it logs the change to your audit system.
Your log-command-execution.js handler logs every command Claude runs: what it was, why it was run, what the output was. This creates a complete audit trail that satisfies SOC 2 and ISO 27001 auditors.
Building Audit-Grade Logging
For regulated environments, your hooks need to log to a system that’s tamper-proof and queryable. Don’t log to files. Use a proper logging service.
We recommend:
- CloudWatch (if you’re on AWS)
- Application Insights (if you’re on Azure)
- Datadog (if you want vendor neutrality)
- Splunk (if you need enterprise-grade search)
Your post-execution hook should log:
- Timestamp (ISO 8601 format)
- User (who triggered this?)
- Action (what did Claude do?)
- Target (what file/system was affected?)
- Result (did it succeed or fail?)
- Context (what was Claude trying to achieve?)
Example:
// scripts/log-command-execution.js
const logger = require('./logger');
module.exports = async (event) => {
logger.info('claude_code_command_executed', {
timestamp: new Date().toISOString(),
user: process.env.USER,
action: event.command,
target: event.workingDirectory,
result: event.exitCode === 0 ? 'success' : 'failure',
context: event.context,
stderr: event.stderr,
});
};
This logging pattern is standard across AI automation frameworks that handle regulated data. It’s not optional for mid-market teams handling customer data.
Status Line Integration for Real-Time Visibility
Hooks are one part of the story. You also need real-time visibility into what Claude is doing. That’s where the statusline comes in.
Statusline Configuration for Team Visibility
The statusline is the one-line summary that appears in your editor while Claude Code is working. By default it shows something like Claude Code: Writing file.... For mid-market teams, you can customise it to show rich context.
Designing Informative Statuslines
Your statusline should answer three questions in under 80 characters:
- What is Claude doing right now?
- What file is it touching?
- Is anything risky happening?
{
"statusline": {
"enabled": true,
"format": "claude_code: {action} [{file}] {risk_indicator}",
"riskIndicators": {
"enabled": true,
"protectedPaths": [
"src/auth/**",
"src/payments/**",
"infrastructure/**"
],
"indicator": "⚠️"
},
"updateFrequency": 500
}
}
With this config, your statusline might show:
claude_code: Reading file [src/utils.js]claude_code: Writing file [src/auth/login.js] ⚠️claude_code: Running tests [test/auth.test.js] ⚠️
That warning indicator tells your team: “Hey, Claude is touching something sensitive. Eyes up.”
Team Dashboards and Monitoring
For larger mid-market teams (50+ engineers), consider building a dashboard that aggregates statuslines and hook logs. This lets your engineering leads see in real-time:
- What Claude is working on across all active sessions
- How many operations are happening in protected directories
- Which engineers are using Claude Code (adoption metrics)
- Error rates and failure patterns
This is especially useful when you’re rolling out Claude Code to a new team. You can spot adoption issues quickly and adjust training or configuration accordingly.
MCP Servers: Extending Claude Code Capabilities
MCP (Model Context Protocol) servers are how Claude Code connects to your infrastructure. Instead of Claude being isolated in your editor, it can query your databases, call your APIs, check your deployments, and interact with your tools.
This is powerful but risky if not configured carefully.
Defining Safe MCP Server Access
Your settings.json should explicitly list which MCP servers Claude Code can access, what permissions they have, and under what conditions.
{
"mcpServers": {
"enabled": true,
"servers": [
{
"name": "database",
"url": "http://localhost:3001",
"permissions": {
"read": ["users", "products", "orders"],
"write": ["logs", "analytics"],
"delete": false,
"allowedOperations": ["SELECT", "INSERT", "UPDATE"]
},
"authentication": {
"type": "api_key",
"keyEnvVar": "CLAUDE_DB_API_KEY",
"rotationPolicy": "quarterly"
},
"rateLimit": {
"requestsPerMinute": 60,
"maxQueryTime": 5000
}
},
{
"name": "git",
"url": "http://localhost:3002",
"permissions": {
"read": true,
"write": ["commit", "push"],
"delete": false
},
"authentication": {
"type": "ssh_key",
"keyPath": "~/.ssh/claude-code-deploy"
}
},
{
"name": "deployment",
"url": "http://localhost:3003",
"permissions": {
"read": true,
"write": false,
"deploy": false
},
"authentication": {
"type": "oauth",
"scope": "read:deployments"
}
}
]
}
}
Notice the granularity: your database MCP server can read from non-sensitive tables and write to logs, but can’t delete anything. Your git server can commit and push, but your deployment server is read-only. Claude can see what’s deployed but can’t trigger deployments.
This is the pattern we use when helping mid-market teams implement AI automation: start with read-only access, prove it’s safe, then gradually expand permissions.
Authentication and Secret Management
Never hardcode secrets in settings.json. Use environment variables, and rotate them regularly.
For teams pursuing SOC 2 compliance, you’ll need to prove that:
- Secrets are never logged
- MCP server connections are encrypted
- Access is audited
- Credentials are rotated on schedule
Your settings.json should reference secret management:
{
"mcpServers": {
"secretManagement": {
"provider": "aws_secrets_manager",
"region": "ap-southeast-2",
"secretPrefix": "claude-code/",
"rotationPolicy": {
"enabled": true,
"rotationDays": 90
}
}
}
}
This tells Claude Code: “Get your secrets from AWS Secrets Manager. They’re rotated every 90 days. Never log them.”
Rate Limiting and Circuit Breakers
MCP servers can become bottlenecks. If Claude Code hammers your database with 1000 queries per minute, you’ll have bigger problems than Claude Code.
Define rate limits and circuit breakers:
{
"mcpServers": {
"rateLimit": {
"global": {
"requestsPerMinute": 300,
"burstSize": 50
},
"perServer": {
"database": 60,
"git": 30,
"deployment": 10
}
},
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5,
"resetTimeout": 60000
}
}
}
With this config, if the database MCP server fails 5 times in a row, Claude Code stops trying for 60 seconds. This prevents cascading failures.
The Portkey guide to Claude Code best practices covers MCP server configuration in detail, including patterns for enterprise teams managing multiple MCP servers.
Real-World Patterns for Regulated Environments
Now let’s put this together into complete settings.json files that actually work for mid-market teams in regulated industries.
Pattern 1: Financial Services (Fintech)
Fintech teams need strict controls, complete audit trails, and zero tolerance for unauthorized data access.
{
"$schema": "https://code.claude.com/schema/settings.json",
"version": "1.0.0",
"projectName": "payment-processing",
"permissionMode": "strict",
"directoryOverrides": {
"./src/payments": "strict",
"./src/auth": "strict",
"./src/compliance": "strict",
"./src/utils": "collaborative",
"./tests": "collaborative",
"./docs": "autonomous"
},
"hooks": {
"beforeFileWrite": {
"enabled": true,
"handler": "scripts/audit-financial.js",
"timeout": 5000
},
"beforeCommandExecution": {
"enabled": true,
"handler": "scripts/validate-command.js",
"timeout": 3000
},
"afterCommandExecution": {
"enabled": true,
"handler": "scripts/log-to-datadog.js",
"timeout": 2000
}
},
"mcpServers": {
"servers": [
{
"name": "database",
"permissions": {
"read": ["audit_logs", "system_config"],
"write": false,
"delete": false
},
"authentication": {
"type": "api_key",
"keyEnvVar": "CLAUDE_DB_READONLY_KEY"
}
}
]
},
"statusline": {
"enabled": true,
"riskIndicators": {
"enabled": true,
"protectedPaths": ["src/payments/**", "src/auth/**"]
}
},
"logging": {
"level": "info",
"destination": "datadog",
"retentionDays": 365
}
}
This pattern is read-only by default. Claude can suggest changes but can’t write them. This is slow but safe for fintech.
Pattern 2: Healthcare (HIPAA-Regulated)
Healthcare teams need to prove data isn’t being accessed inappropriately. Every interaction with patient data must be logged.
{
"$schema": "https://code.claude.com/schema/settings.json",
"version": "1.0.0",
"projectName": "patient-portal",
"permissionMode": "collaborative",
"dataClassification": {
"enabled": true,
"piiDetection": true,
"phiDetection": true,
"blockedPatterns": [
"(\\d{3}-\\d{2}-\\d{4})",
"(\\d{10}|\\d{3}-\\d{3}-\\d{4})"
]
},
"directoryOverrides": {
"./src/patient-data": "strict",
"./src/phi-processing": "strict",
"./src/api": "collaborative",
"./src/ui": "collaborative"
},
"hooks": {
"beforeFileRead": {
"enabled": true,
"handler": "scripts/audit-phi-access.js",
"timeout": 3000
},
"afterFileRead": {
"enabled": true,
"handler": "scripts/log-phi-access.js",
"timeout": 2000
},
"onDataAccess": {
"enabled": true,
"handler": "scripts/notify-compliance.js",
"timeout": 2000
}
},
"logging": {
"level": "info",
"destination": "splunk",
"includeContext": true,
"retentionDays": 2555
}
}
Notice the dataClassification section. This detects PII and PHI (Protected Health Information) patterns and prevents Claude from writing them to logs. The hooks log every data access, creating a complete audit trail for HIPAA audits.
Pattern 3: SaaS (SOC 2 Type II)
SaaS companies need to balance speed with auditability. Most code is safe, but anything touching customer data needs oversight.
{
"$schema": "https://code.claude.com/schema/settings.json",
"version": "1.0.0",
"projectName": "saas-platform",
"permissionMode": "collaborative",
"directoryOverrides": {
"./src/auth": "strict",
"./src/customer-data": "collaborative",
"./src/billing": "collaborative",
"./src/api": "collaborative",
"./src/internal": "autonomous",
"./tests": "autonomous"
},
"hooks": {
"afterCommandExecution": {
"enabled": true,
"handler": "scripts/log-to-cloudwatch.js",
"timeout": 2000
},
"onApproval": {
"enabled": true,
"handler": "scripts/record-approval.js",
"timeout": 1000
}
},
"mcpServers": {
"servers": [
{
"name": "database",
"permissions": {
"read": true,
"write": ["logs", "analytics"],
"delete": false
},
"rateLimit": {
"requestsPerMinute": 120
}
}
]
},
"logging": {
"level": "info",
"destination": "cloudwatch",
"retentionDays": 365
},
"complianceMode": {
"enabled": true,
"standards": ["SOC2", "ISO27001"]
}
}
This pattern lets Claude move fast on internal code and tests, but requires approval for anything touching customer data. It’s the sweet spot for most SaaS companies.
Implementation Roadmap for Your Team
Having a great settings.json is useless if your team doesn’t understand it or follow it. Here’s how to roll this out successfully.
Phase 1: Assessment (Week 1)
First, understand where you are:
- Audit current usage: How is your team using Claude Code today? Are they using it on sensitive code? Are there any security incidents?
- Identify protected directories: What code is sensitive? Auth, payments, customer data, infrastructure?
- Map your MCP servers: What systems does Claude need to interact with? Database? Git? Deployment systems?
- Review compliance requirements: Are you pursuing SOC 2 compliance? ISO 27001? HIPAA? This drives your settings.
Phase 2: Design (Week 2-3)
Work with your security and engineering leads to design your settings:
- Define permission model: What’s your baseline? Collaborative is usually right for mid-market.
- List protected directories: Be specific.
./src/auth/**, not just./src. - Design your hooks: What do you need to log? What do you need to approve?
- Plan MCP server access: What can Claude read? Write? Delete?
- Get buy-in: Share the design with your team. Make sure it makes sense.
We typically recommend starting conservative (more restrictions) and loosening over time as your team proves it’s safe. It’s easier to add permissions than to tighten them after an incident.
Phase 3: Implementation (Week 4-6)
Roll out your settings:
- Create global settings: Add
~/.claude/settings.jsonto your engineering onboarding checklist. - Commit project settings: Add
.claude/settings.jsonto your repo. Require code review for changes. - Implement hooks: Write your audit and logging handlers. Test them.
- Configure MCP servers: Set up your servers, test permissions, verify logging.
- Train your team: Show them what the new settings mean. Demo the approval workflow.
Phase 4: Monitoring (Week 7+)
Once live, monitor and iterate:
- Track metrics: How many approvals per day? How many rejections? How many MCP calls?
- Gather feedback: Is collaborative mode too slow? Are hooks logging the right things?
- Adjust permissions: Based on real usage, tighten or loosen specific directories.
- Audit regularly: Monthly, review logs. Look for patterns. Are there any near-misses?
When you’re ready to pursue compliance (SOC 2, ISO 27001), you’ll already have 3 months of audit logs to show auditors. That’s invaluable.
Common Pitfalls and How to Avoid Them
Pitfall 1: Overly Permissive Settings
The mistake: Setting everything to autonomous mode because it’s faster.
Why it fails: You ship a bug that breaks production. Claude Code gets blamed. Your team loses trust. You spend 6 months rebuilding credibility.
The fix: Start conservative. Autonomous mode only for internal tools and documentation. Everything else: collaborative or strict.
Pitfall 2: Hooks That Are Too Slow
The mistake: Your pre-execution hook makes 3 API calls, checks a database, and queries your compliance system. It takes 10 seconds per operation.
Why it fails: Your team disables hooks because they’re slowing down work. Now you have no audit trail.
The fix: Keep hooks fast. Pre-execution hooks should take <2 seconds. Log asynchronously. Use circuit breakers to fail fast if a service is slow.
Pitfall 3: Secrets in Logs
The mistake: Your hook logs the full command Claude executed, including API keys.
Why it fails: Your logs contain secrets. A breach exposes your infrastructure. Auditors fail you on SOC 2.
The fix: Sanitise logs. Strip out environment variables, API keys, and credentials. Use a secrets manager. Rotate frequently.
The eesel guide to settings.json configuration covers common pitfalls in detail.
Pitfall 4: Directory Overrides That Don’t Match Reality
The mistake: You define ./src/auth as strict mode, but your team’s auth code is actually in ./src/authentication/handlers.
Why it fails: Claude Code applies the wrong permission level. Either it’s too permissive and bypasses your controls, or too restrictive and your team disables it.
The fix: Map your actual directory structure. Use glob patterns. Test with real files before rolling out.
Pitfall 5: MCP Servers Without Rate Limits
The mistake: You give Claude Code unlimited access to your database MCP server.
Why it fails: Claude Code runs a query that takes 30 seconds and locks your database. Your customers’ requests timeout. You lose revenue.
The fix: Always set rate limits. Start conservative (60 requests per minute). Monitor actual usage. Adjust based on real data.
Next Steps and Compliance Readiness
If you’re a mid-market team in Sydney or Australia, Claude Code is a competitive advantage—but only if it’s configured correctly. A poorly configured Claude Code installation is a liability. A well-configured one is a force multiplier that lets you ship faster and safer.
Immediate Actions (This Week)
- Review your current Claude Code usage: Are you using it on sensitive code? What could go wrong?
- Identify your compliance requirements: SOC 2? ISO 27001? HIPAA? This drives your settings.
- Read the official docs: The Claude Code settings documentation is the source of truth. Spend 30 minutes with it.
Short-Term Actions (Next 4 Weeks)
- Design your settings.json: Work with your security and engineering leads. Document your decisions.
- Implement hooks and logging: Get audit trails in place before you need them.
- Configure MCP servers: Map what Claude needs to access. Set permissions and rate limits.
- Train your team: Make sure everyone understands the new settings and approval workflow.
Medium-Term Actions (2-3 Months)
- Monitor and iterate: Track metrics. Gather feedback. Adjust permissions based on real usage.
- Build compliance evidence: Your logs are audit gold. Start organizing them for compliance reviews.
- Plan for scale: As your team grows, how will you manage settings across multiple projects?
When You’re Ready for Professional Support
If you’re pursuing SOC 2 or ISO 27001 compliance, and you want to integrate Claude Code into your audit-ready infrastructure, that’s where we come in. At PADISO, we help mid-market and enterprise teams in Sydney and across Australia:
- Design Claude Code configurations that satisfy auditors
- Implement hooks and logging that create tamper-proof audit trails
- Integrate MCP servers securely with proper authentication and rate limiting
- Build compliance evidence that speeds up SOC 2 and ISO 27001 audits
- Train your team on agentic AI patterns that balance speed with safety
We’ve helped teams move from “Claude Code is a risk” to “Claude Code is part of our audit-ready infrastructure.” It’s not magic—it’s careful configuration, clear policy, and good logging.
Resources for Deeper Learning
For more on Claude Code patterns, check out:
- The official Claude Code overview from Anthropic
- The Builder.io guide to Claude Code settings
- The Portkey best practices for enterprise teams
- The agentic workflow patterns guide
For mid-market teams implementing AI automation more broadly, explore how agentic AI differs from traditional automation and why the architectural decisions matter.
If you’re building customer-facing AI features, understand how AI automation transforms customer service, e-commerce personalisation, and financial services operations.
Summary
Claude Code settings.json isn’t just configuration—it’s your governance layer. It’s how you let Claude move fast while keeping your team safe. It’s how you prove to auditors that you’re using AI responsibly.
The teams moving fastest are the ones with clear permission models, automated hooks that log decisions, and MCP server integrations that keep Claude in the right guardrails. They’re shipping faster because they’re shipping safer.
Start with the patterns in this guide. Adapt them to your specific risks and compliance requirements. Monitor what happens. Iterate based on real usage. In 3 months, you’ll have an audit-ready Claude Code setup that your team trusts and your auditors respect.
That’s the goal. Get there, and Claude Code becomes a genuine competitive advantage.