Project Settings Configuration

Configure Distill at the project level using .claude/settings.local.json. This file overrides global settings for a specific project.

File Location

Create the file at your project root:

your-project/
├── .claude/
│   └── settings.local.json
├── CLAUDE.md
├── src/
└── ...

Complete Template

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp"],
      "env": {}
    }
  },
  "permissions": {
    "allow": [
      "mcp__distill__smart_file_read",
      "mcp__distill__auto_optimize",
      "mcp__distill__code_execute",
      "mcp__distill__discover_tools",
      "mcp__distill__session_stats",
      "mcp__distill__register_model"
    ]
  }
}

Configuration Options

MCP Servers

Configure the Distill MCP server:

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp"],
      "env": {}
    }
  }
}

Alternative with global install:

{
  "mcpServers": {
    "distill": {
      "command": "distill-mcp",
      "args": ["serve"],
      "env": {}
    }
  }
}

Tool Permissions

Pre-approve Distill tools to avoid permission prompts:

{
  "permissions": {
    "allow": [
      "mcp__distill__smart_file_read",
      "mcp__distill__auto_optimize",
      "mcp__distill__code_execute",
      "mcp__distill__discover_tools",
      "mcp__distill__session_stats",
      "mcp__distill__register_model",
      "mcp__distill__summarize_logs",
      "mcp__distill__compress_context",
      "mcp__distill__analyze_build_output",
      "mcp__distill__deduplicate_errors",
      "mcp__distill__semantic_compress",
      "mcp__distill__code_skeleton",
      "mcp__distill__diff_compress",
      "mcp__distill__context_budget"
    ]
  }
}

Minimal permissions (core tools only):

{
  "permissions": {
    "allow": [
      "mcp__distill__smart_file_read",
      "mcp__distill__auto_optimize",
      "mcp__distill__code_execute",
      "mcp__distill__discover_tools"
    ]
  }
}

Minimal Setup

For quick setup, use this minimal configuration:

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp"]
    }
  },
  "permissions": {
    "allow": [
      "mcp__distill__*"
    ]
  }
}

The wildcard mcp__distill__* allows all Distill tools without individual prompts.

Global vs Project Settings

File	Location	Scope
`~/.claude/settings.json`	Home directory	All projects
`.claude/settings.local.json`	Project root	Current project only

Project settings override global settings. Use project settings when:

Different projects need different MCP configurations
You want to share settings with your team (commit to git)
You need project-specific tool permissions

Auto-Setup with CLI

Generate the configuration automatically:

# In your project directory
distill-mcp setup --local

This creates .claude/settings.local.json with the recommended configuration.

Combining with CLAUDE.md

For optimal setup, use both files:

.claude/settings.local.json - MCP server and permissions
CLAUDE.md - Usage instructions for Claude

your-project/
├── .claude/
│   └── settings.local.json  # Server config + permissions
├── CLAUDE.md                 # Usage guidelines
└── ...

Git Configuration

Commit to Repository (Recommended)

Share settings with your team by committing the file:

git add .claude/settings.local.json
git commit -m "chore: add Distill MCP configuration"

Keep Private

If you don't want to commit settings, add to .gitignore:

.claude/settings.local.json

Environment Variables

Pass environment variables to the MCP server:

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp"],
      "env": {
        "CTXOPT_DEBUG": "true",
        "CTXOPT_LOG_LEVEL": "info"
      }
    }
  }
}

Troubleshooting

Settings Not Applied

Restart Claude Code after creating/modifying the file

Verify JSON syntax is valid:

cat .claude/settings.local.json | python -m json.tool

Check file location (must be at project root in .claude/ folder)

MCP Server Not Starting

Run doctor to check installation:
```
distill-mcp doctor
```
Try running the server manually:
```
npx distill-mcp serve
```

Permission Denied Errors

Add the specific tool to the permissions.allow array or use the wildcard pattern mcp__distill__*.

Complete Example

Full configuration with all options:

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp"],
      "env": {}
    }
  },
  "permissions": {
    "allow": [
      "mcp__distill__smart_file_read",
      "mcp__distill__auto_optimize",
      "mcp__distill__code_execute",
      "mcp__distill__discover_tools",
      "mcp__distill__session_stats",
      "mcp__distill__register_model"
    ]
  }
}

This configuration:

Enables the Distill MCP server
Pre-approves core tools for seamless usage
Works with both global and local installations

Project Settings Configuration

On this page