## How it works

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.

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 is 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.