How to Configure Cline settings.json & Global State

While many developers expect Visual Studio Code extensions to store all configuration in the user-facing settings.json file, over 90% of Cline configuration is stored directly in VS Code's internal SQLite database, globalState.vscdb, making simple settings syncing impossible [Cline GitHub Documentation 2026]. Because Cline relies on VS Code's native SecretStorage and globalState APIs, configuration is tied to the local machine's application data directory. This design is highly secure and prevents sensitive credentials from leaking into your dotfiles, but it introduces a major gap for developers moving between machines or spinning up remote devcontainers. Your configurations, custom rules, and conversation tasks are lost when the environment is rebuilt. Cline's global settings bypass standard workspace-level preferences, which is further explored in our guide on storage for agents.

To manage this, you must understand how VS Code isolates data. The editor provides two distinct APIs for extension developers: globalState for non-sensitive data and SecretStorage for credentials. Cline stores the selected LLM provider, custom system prompts, temperature settings, and task history metadata inside the globalState SQLite database. Meanwhile, API keys and access tokens are routed to SecretStorage, which delegates storage to the operating system's native keychain manager. Consequently, copying your VS Code user settings folder to a new machine will not carry over your Cline environment.

Because these files are hidden within system directories, configuring them requires targeting the correct paths. For instance, the Model Context Protocol settings are kept in a separate JSON file named cline_mcp_settings.json located within the extension's global storage folder. If you destroy a remote virtual machine or rebuild a Docker container, this file is deleted, which resets your active MCP servers.

Finding the configuration directories on your local drive is the first step toward creating a reliable backup. The exact directory locations depend on your operating system and the flavor of VS Code you are running. If you are using the standard stable release, the directories reside in your application support folder.

The table below outlines the exact disk paths for different configuration files and credentials across macOS, Windows, and Linux:

If you are using VS Code Insiders, replace the Code folder in the paths with Code - Insiders. For the CLI version of Cline, the configuration path shifts to the user's home directory under ~/.cline/data/settings/.

To inspect the SQLite database, you can use any database browser. The state.vscdb database contains a single table named ItemTable with two columns: key and value. Cline's settings are stored under the extension identifier saoudrizwan.claude-dev. Modifying these SQLite rows manually is risky and can corrupt your editor state, so always close VS Code before performing any manual updates.

The cline_mcp_settings.json file is a critical component of the Cline extension, as it defines how the agent communicates with external tools. The file uses a standard JSON schema where each key represents an MCP server name, and the value contains the server's command, arguments, and environment variables. If you make a syntax error in this file, Cline will fail to load any tools.

Below is an example of a valid cline_mcp_settings.json configuration, showing how to define local and remote MCP servers:

{
  "mcpServers": {
    "git-manager": {
      "command": "node",
      "args": [
        "/path/to/git-mcp/index.js"
      ],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin"
      },
      "disabled": false
    },
    "fastio-workspace": {
      "command": "npx",
      "args": [
        "-y",
        "@fastio/mcp-server"
      ],
      "env": {
        "FASTIO_API_KEY": "your_secure_api_key_here"
      },
      "disabled": false
    }
  }
}

When troubleshooting MCP issues, the first place to look is the MCP tab in the Cline sidebar. Setting up Cline's connection to MCP servers is detailed in our guide on storage for agents. If a server is marked as red or disabled, it is usually due to one of three common issues:

1. Incorrect Command Paths: If the command requires node or npx, make sure the executable is present on the system path. In remote SSH sessions, the extension shell might not load your interactive shell profile, meaning that custom node installations (like those managed by nvm) are not visible. You can resolve this by specifying the absolute path to the node executable in the command field.

2. Missing Environment Variables: MCP servers often require API tokens or path configurations. These must be defined within the env object inside the JSON file. VS Code will not automatically pass your local environment variables to the MCP server processes.

3. Node Version Mismatches: Some modern MCP servers require Node.js version 18 or higher. If the host machine is running an older LTS release, the server will fail during initialization. You can verify this by checking the extension logs in the VS Code Output panel under the "Cline MCP" dropdown.

When working with devcontainers, GitHub Codespaces, or remote servers via SSH, the local container or virtual machine is often rebuilt from scratch. This rebuild destroys the globalStorage folder, erasing your MCP configurations and forcing you to re-authenticate with your AI provider. While VS Code Settings Sync handles editor-wide settings, it does not persist the underlying SQLite state database or the cline_mcp_settings.json file.

To solve this state loss in container environments, you can configure your devcontainer.json file to mount a persistent volume. This volume maps the extension's global storage directory on the host machine to the container's virtual directory.

The JSON example below demonstrates how to configure a mount point in your devcontainer.json file to persist your MCP configurations:

{
  "name": "Node.js & Cline Workspace",
  "dockerFile": "Dockerfile",
  "mounts": [
    "source=cline-global-storage,target=/home/node/.config/Code/User/globalStorage/saoudrizwan.claude-dev,type=volume"
  ],
  "customizations": {
    "vscode": {
      "extensions": [
        "saoudrizwan.claude-dev"
      ]
    }
  }
}

By mapping the directory to a named volume, VS Code preserves your task logs and settings across container rebuilds. For remote SSH servers, you can achieve a similar result by using a persistent user directory and running a symbolic link from your server's application directory to a backup folder on your home drive.

For the API keys stored in SecretStorage, mounting folders is insufficient because the secrets are managed by the operating system's credential manager. In remote environments that lack a desktop keychain, VS Code falls back to a file-based mock keychain or prompts you for the API key on each session launch. You can automate key injection by defining the keys as environment variables in your remote shell profile.

Secure your agent workflows with versioned storage

Set up your Fast.io team workspace to store Cline assets with built-in version history, hybrid search, and Metadata Views. Every organization begins with a 14-day free trial.

Start 14-Day Trial

Relying on local virtual volumes or temporary container files is fragile when multiple agents are collaborating or when you need a permanent record of the agent's work. Instead of keeping files stored inside an ephemeral container, team-oriented development benefits from externalizing the workspace.

You can configure Cline to read and write files directly within Fast.io's cloud workspace platform. Fast.io serves as a persistent, versioned file storage layer for your AI agents. Fast.io provides persistent workspaces with Streamable HTTP access and legacy SSE configurations. Decoupling the agent's output files from the local container's disk ensures that even if your remote workspace resets, your project assets remain secure and accessible on the web.

Fast.io provides several capabilities designed for agentic workflows:

• Per-File Version History: Every time Cline modifies a file, Fast.io records the changes in a complete history log. This lets humans track and revert edits without relying on manual git commits.

• Granular Permissions: You can set permissions at the organization, workspace, folder, or file level to control what your agent can read or write.

• Intelligence Mode: Enabling this mode auto-indexes workspace files for hybrid search, which combines semantic search and full-text search. The agent can query these documents directly with citations.

• Metadata Views: Fast.io turns unstructured files into structured tables using natural language. Instead of relying on manual parsing or rigid layout tools, Metadata Views extract specific fields to populate filterable spreadsheets, which you can link to our product page on Metadata Views.

• Append-Only Audit Log: Every file change, access request, and agent operation is written to an unalterable log, providing a complete audit trail for compliance and safety.

In a typical developer handoff workflow, a developer starts a 14-day free trial of a Fast.io organization, which requires a credit card. An agent can set up the workspace, write the code and collaborative notes, and then hand over ownership to the human client, who takes over billing. The plans scale from Starter at $29 per month, to Business at $99 per month, and Growth at $299 per month, ensuring that you have dedicated resources for commercial workloads.

If you are moving to a new computer or want to secure your configuration against accidental data loss, you can run a manual backup script. A simple shell script can package your MCP server configurations and task logs into a compressed folder.

The Bash script below automates the backup of your Cline configuration and task folders:

#!/bin/bash

### Define backup directory
BACKUP_DIR="$HOME/cline_backups/\$(date +%Y-%m-%d)"
mkdir -p "\$BACKUP_DIR"

### VS Code storage paths for macOS
VSCODE_GLOBAL_STORAGE="\$HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev"

echo "Starting backup of Cline settings..."

### Copy MCP configuration
if [ -f "\$VSCODE_GLOBAL_STORAGE/settings/cline_mcp_settings.json" ]; then
    mkdir -p "\$BACKUP_DIR/settings"
    cp "\$VSCODE_GLOBAL_STORAGE/settings/cline_mcp_settings.json" "\$BACKUP_DIR/settings/"
    echo "Backed up cline_mcp_settings.json."
fi

### Copy Task history
if [ -d "\$VSCODE_GLOBAL_STORAGE/tasks" ]; then
    cp -r "\$VSCODE_GLOBAL_STORAGE/tasks" "\$BACKUP_DIR/"
    echo "Backed up task history logs."
fi

### Compress the backup folder
tar -czf "\$HOME/cline_backup_latest.tar.gz" -C "\$HOME/cline_backups" "\$(date +%Y-%m-%d)"
echo "Backup complete! File saved as \$HOME/cline_backup_latest.tar.gz"

To restore the files on a new machine, you unpack the archive and copy the files back to the corresponding global storage folder. Because SecretStorage uses the operating system's native keychain, you must manually enter your API keys in the sidebar when running the extension for the first time on your new computer.

If you are using the CLI version of Cline, the backup process is even simpler. You can copy the contents of the ~/.cline/data/settings/ directory, which contains your provider definitions and global settings. Version controlling these files in a private repository is a good practice, but you must ensure that no sensitive API keys are stored in plaintext before committing them to Git.