MCP Servers

Updated September 18, 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.

You pick a project’s servers in Gem Settings (or in the New Gem panel before creation); crystl writes the project’s .mcp.json when you save.

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)

Managing servers per project

Each gem can have a different set of active MCP servers. The global MCP Servers settings page sets which catalog servers are on by default for new gems; the per-project selection lives in Gem Settings > agents, in the MCP section. Saving the gem updates its .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.