MCP Servers

Updated March 22, 2026

Crystl manages a global catalog of MCP servers and syncs the active ones to each project so Claude Code picks them up automatically. No manual .mcp.json editing required.

How It Works

Crystl maintains a central list of MCP servers at ~/.config/crystl/mcps.json. For each project, you choose which servers to enable. Crystl writes the active server configuration to the project’s .mcp.json file, which Claude Code reads on startup.

When you toggle a server on or off for a project, Crystl updates that project’s .mcp.json immediately.

Adding a Server

  1. Open Settings > MCP Servers (Cmd + , then navigate to MCP Servers)
  2. Click Add Server
  3. Fill in the server details:
    • Name — A label for the server
    • Command — The executable to run (e.g., npx)
    • Args — Command arguments (e.g., @modelcontextprotocol/server-filesystem)
    • URL — For remote servers, the endpoint URL
    • Env — Environment variables the server needs

Managing Servers Per Project

Each gem can have a different set of active MCP servers. From the MCP Servers settings panel, toggle servers on or off for the current project. Crystl updates the project’s .mcp.json to match.

This means you can have a filesystem server active in one project and a database server in another, all managed from one place.

The Global Catalog

The catalog at ~/.config/crystl/mcps.json holds every server you’ve configured. Servers in the catalog are available to toggle on in any project but aren’t active anywhere until you enable them.

Adding a server to the catalog does not affect any project until you explicitly turn it on.

Availability

MCP server management is available on all plans, including Free.