5.3 Deep Link Protocol

Overview

CC Switch supports the ccswitch:// deep link protocol, enabling one-click configuration import via links.

Use cases:

Team configuration sharing
One-click setup in tutorials
Quick sync across devices

Online Generator Tool

CC Switch provides an online deep link generator tool:

URL: https://farion1231.github.io/cc-switch/deplink.html

How to Use

Open the above URL
Select the import type (Provider/MCP/Prompt)
Fill in the configuration information
Click "Generate Link"
Copy the generated deep link
Share with others or use on other devices

Protocol Format

V1 Protocol

Uses URL parameter format, easy to read and generate:

ccswitch://v1/import?resource={type}&app={app}&name={name}&...

Common parameters:

Parameter	Required	Description
`resource`	Yes	Resource type: `provider` / `mcp` / `prompt` / `skill`
`app`	Yes	App type: `claude` / `codex` / `gemini` / `opencode` / `openclaw`
`name`	Yes	Name

Provider parameters (resource=provider):

Parameter	Required	Description
`endpoint`	No	API endpoint URL (supports comma-separated multiple URLs)
`apiKey`	No	API key
`homepage`	No	Provider website
`model`	No	Default model
`haikuModel`	No	Haiku model (Claude only)
`sonnetModel`	No	Sonnet model (Claude only)
`opusModel`	No	Opus model (Claude only)
`notes`	No	Notes
`icon`	No	Icon
`config`	No	Base64-encoded configuration content
`configFormat`	No	Configuration format: `json` / `toml`
`configUrl`	No	Remote configuration URL
`enabled`	No	Whether to enable (boolean)
`usageScript`	No	Usage query script
`usageEnabled`	No	Whether to enable usage query (default true)
`usageApiKey`	No	Usage query API Key
`usageBaseUrl`	No	Usage query base URL
`usageAccessToken`	No	Usage query access token
`usageUserId`	No	Usage query user ID
`usageAutoInterval`	No	Auto query interval (minutes)

Prompt parameters (resource=prompt):

Parameter	Required	Description
`content`	Yes	Prompt content
`description`	No	Description
`enabled`	No	Whether to enable (boolean)

MCP parameters (resource=mcp):

Parameter	Required	Description
`apps`	Yes	App list (comma-separated, e.g., `claude,codex,gemini,opencode`)
`config`	Yes	MCP server configuration (JSON format)
`enabled`	No	Whether to enable (boolean)

Skill parameters (resource=skill):

Parameter	Required	Description
`repo`	Yes	Repository (format: `owner/name`)
`directory`	No	Directory path
`branch`	No	Git branch

Example:

ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx

Import Type Examples

Import Provider

ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx

Import MCP Server

ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch

Import Prompt Preset

ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6

Import Skill

ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main

Generate Deep Links

Manual Generation

Prepare parameters
Assemble the URL following V1 protocol format
URL-encode special characters

Example:

javascript

const params = new URLSearchParams({
  resource: 'provider',
  app: 'claude',
  name: 'My Provider',
  endpoint: 'https://api.example.com',
  apiKey: 'sk-xxx'
});

const url = `ccswitch://v1/import?${params.toString()}`;

Online Tool

Using CC Switch's official online deep link generator tool is more convenient.

Using Deep Links

Click the Link

Click a deep link in a browser or other application:

The system asks whether to open CC Switch
After confirming, CC Switch opens
An import confirmation dialog is displayed
Confirm the import

Import Confirmation

A confirmation dialog is shown before import, containing:

Import type
Configuration preview
Confirm/Cancel buttons

Security tip: Only import configurations from trusted sources.

Protocol Registration

Automatic Registration

CC Switch automatically registers the ccswitch:// protocol during installation.

Manual Registration

If the protocol is not registered correctly:

macOS: Reinstall the app, or run:

bash

/usr/bin/open -a "CC Switch" --args --register-protocol

Windows: Reinstall the app, or check the registry:

HKEY_CLASSES_ROOT\ccswitch

Linux: Check the MimeType configuration in the .desktop file.

Security Considerations

Sensitive Information

Deep links may contain sensitive information (e.g., API Keys):

Do not share links containing API Keys in public
Remove or replace sensitive information before sharing
Use secure channels to transmit links

Source Verification

Before import, CC Switch will:

Validate the data format
Display a configuration preview
Require user confirmation

Malicious Link Protection

CC Switch checks:

Whether the data format is valid
Whether required fields are complete
Whether configuration values are within reasonable ranges

Example Links

Example: Import Claude Provider

ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com

Example: Import MCP Server

ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D

Troubleshooting

Link Won't Open

Check:

Is CC Switch installed
Is the protocol registered correctly
Is the link format correct

Import Failed

Possible causes:

Base64 encoding error
JSON format error
Missing required fields

Solutions:

Check the original JSON format
Re-encode in Base64
Ensure all required fields are present