Skip to content

mcp-client-compatibility.md

Latest commit

 

History

History
43 lines (32 loc) · 4.58 KB

mcp-client-compatibility.md

File metadata and controls

43 lines (32 loc) · 4.58 KB

MCP Client Compatibility

Setlist can detect supported MCP clients, preview the managed setlist server entry it would write, apply or remove that entry with backups, and show recovery guidance afterward. Detection is based on real client artifacts such as app bundles or binaries, not config files alone.

Run a dry-run first:

setlist mcp-clients detect
setlist mcp-clients plan --client all

Then install only after reviewing the plan:

setlist mcp-clients install --client claude-desktop --yes
setlist mcp-clients install --client codex --yes

To remove Setlist later, run the guarded remove command without --yes first. It previews the deletion and backup path without writing:

setlist mcp-clients remove --client claude-desktop
setlist mcp-clients remove --client claude-desktop --yes

Matrix

Client Detection signal Setlist uses Config path Config format Install/remove behavior Backup behavior Unmanaged entries and conflicts Recovery guidance Known limits
Claude Desktop /Applications/Claude.app must exist. A config file by itself does not count as an installed client. ~/Library/Application Support/Claude/claude_desktop_config.json JSON, using the mcpServers object. Adds or updates a Setlist-managed setlist MCP server entry that runs npx -y @setlist/mcp. Remove deletes only that managed entry. If the config is missing or Setlist is absent, remove is a structured no-op. Existing config files are copied to a timestamped .setlist-backup-... file before Setlist writes during install or remove. No backup is needed when Setlist creates a new missing config file. Preserves unmanaged MCP servers in mcpServers. Refuses to overwrite, adopt, or remove an unmanaged server named setlist; you must rename or remove that entry manually when it is not Setlist-managed. Available in CLI plan/install/remove output and in App Settings install/remove preview/apply controls. Guidance names the config path, backup path when applicable, preserved unmanaged servers, and manual next steps for conflicts or rollback. Does not install Claude Desktop, restart Claude Desktop, validate the @setlist/mcp package launch inside Claude, auto-restore backups, delete config files, or remove unmanaged entries. JSON configs must parse safely before Setlist writes.
Codex Either a codex binary on PATH or /Applications/Codex.app must exist. A config file by itself does not count as an installed client. ~/.codex/config.toml TOML, using mcp_servers sections. Adds or updates a Setlist-managed [mcp_servers.setlist] section that runs npx -y @setlist/mcp. Remove deletes only that managed section and its nested env section. If the config is missing or Setlist is absent, remove is a structured no-op. Existing config files are copied to a timestamped .setlist-backup-... file before Setlist writes during install or remove. No backup is needed when Setlist creates a new missing config file. Preserves unmanaged MCP server sections. Refuses to overwrite, adopt, or remove an unmanaged server named setlist; you must rename or remove that section manually when it is not Setlist-managed. Available in CLI plan/install/remove output and in App Settings install/remove preview/apply controls. Guidance names the config path, backup path when applicable, preserved unmanaged servers, and manual next steps for conflicts or rollback. Does not install Codex, restart Codex, validate the @setlist/mcp package launch inside Codex, auto-restore backups, delete config files, or remove unmanaged entries. Setlist manages only its own mcp_servers.setlist section and leaves other TOML content alone.

Safety Contract

  • Config-file presence alone is not proof that a client is installed.
  • plan reports detected/not detected state, config path, existing server names, unmanaged preservation, conflicts, and backup intent without writing files.
  • install backs up an existing config before writing and only writes the managed Setlist entry.
  • remove backs up an existing config before writing and removes only a managed Setlist entry.
  • Managed Setlist entries are marked with __setlist = true or "__setlist": true, depending on the client format.
  • Unmanaged MCP servers are preserved.
  • An unmanaged server named setlist is treated as a conflict and left untouched.
  • Backup restoration is manual. Setlist tells you which file to restore, but it will not restore backups automatically.
  • App Settings exposes guarded install and remove previews plus apply controls for managed Setlist entries.