Configuration & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
The Continuous Claude system utilizes a multi-layered configuration strategy to manage Model Context Protocol (MCP) servers, local environment secrets, and session state. The architecture prioritizes a "local-first" approach, allowing the system to run 100% offline by providing local alternatives for paid services and managing configuration through JSON manifests and .env files.
The configuration system handles two primary domains:
- Global/Project Settings: Managed via
mcp_config.jsonand.mcp.jsonto define MCP server behaviors and transports. - Environment Secrets: Managed via
.envfiles to store API keys for optional external services and localized paths.
Sources: CLAUDE_ONBOARDING.md, CLAUDE.md, install-global.sh:427-440
MCP Server Configuration
Continuous Claude identifies MCP servers through structured JSON files. The runtime discovery logic follows a specific precedence to allow for both global tools and project-specific overrides.
Configuration Hierarchy
The McpClientManager and wrapper generation tools look for configurations in the following order:
- .mcp.json: The primary project-level configuration (Claude Code convention).
- mcp_config.json: A project-level fallback or example file.
- ~/.claude/mcp_config.json: Global configuration applied across all projects.
Sources: CLAUDE.md, src/runtime/generate_wrappers.py:168-202
Transport Types and Schema
The configuration supports multiple transport protocols for MCP servers. Each server definition in the mcpServers object must specify a type and corresponding connection parameters.
| Transport Type | Key Parameters | Description |
|---|---|---|
stdio | command, args, env | Standard input/output communication via subprocess. |
sse | url, headers | Server-Sent Events over HTTP. |
http | url, headers | Streamable HTTP communication. |
Sources: CLAUDE.md, src/runtime/generate_wrappers.py:223-234
Configuration Data Flow
The following diagram illustrates how the system resolves and merges configuration files during the wrapper generation process.
The merging logic ensures that project-specific tool versions or environment variables take precedence over global settings.
Sources: src/runtime/generate_wrappers.py:168-210
Environment Variables and Secrets
Sensitive information, such as API keys for optional services (e.g., Firecrawl, Perplexity), is stored in .env files. The system uses a template-based approach to ensure required keys are present while preserving existing user values.
The .env Management System
During global installation, the merge_env_files function performs a non-destructive update of the .env file located in the $HOME/.claude directory.
- Source Template:
.env.example - Target File:
~/.claude/.env - Logic: It adds missing keys from the template but never overwrites existing values.
Sources: install-global.sh:65-98, install-global.sh:444-446
Key Environment Variables
| Variable | Purpose | Related Tool/Script |
|---|---|---|
FIRECRAWL_API_KEY | Web scraping via Firecrawl | scripts/firecrawl_scrape.py |
CLAUDE_PROJECT_DIR | Required for hook execution | .claude/hooks/ |
${VAR} Placeholders | Used within mcp_config.json for dynamic paths | MCP Runtime |
Sources: CLAUDE.md, scripts/README.md, tests/test_artifact_index.py:28-30
Local Path and Directory Configuration
The project uses several specific directories for caching and state management, which are initialized during the project setup phase.
Global Directory Structure (~/.claude)
- skills/: Global tool definitions in SKILL.md format.
- hooks/: Event handlers (SessionStart, PostToolUse).
- settings.json: Hook registrations and global parameters.
- cache/artifact-index/: Contains
context.dbfor the Context Graph.
Sources: CLAUDE_ONBOARDING.md, install-global.sh:427-456
Project Directory Initialization
The init-project.sh script configures the local project environment, supporting two distinct modes:
Sources: init-project.sh:100-190
Tool Safety and Discovery Configuration
A specialized configuration module, generate_test_params.py, classifies tools based on their names and descriptions to prevent the accidental execution of destructive operations during automated discovery.
Safety Classification Patterns
Tools are categorized into SAFE, DANGEROUS, or UNKNOWN using regex patterns.
- Safe Patterns:
^get_,^list_,^search_,^read_,^show_. - Dangerous Patterns:
^delete_,^remove_,^drop_,^update_,^write_.
Sources: src/runtime/generate_test_params.py:44-90
Discovery Metadata
The discovery_config.json (generated via uv run mcp-generate-discovery) contains the result of this classification, identifying which tools are safe for automated schema probing.
{
"servers": {
"git": {
"safeTools": {
"git_log": {"repo_path": ".", "max_count": 1}
}
}
},
"metadata": {
"tools_skipped": {"dangerous": ["delete_repo"], "unknown": []}
}
}
Sources: src/runtime/generate_test_params.py:326-350
Summary
Continuous Claude uses a layered configuration system starting with global defaults in ~/.claude/ and allowing granular overrides via project-level .mcp.json files. Environment secrets are isolated in .env files, while the init-project.sh and install-global.sh scripts automate the provisioning of necessary directory structures and databases. This architecture ensures that the system can operate seamlessly across different environments while maintaining strict safety standards for MCP tool execution.