# MCP Servers

> Manage a global catalog of MCP servers and sync them to projects automatically.

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.

---
Source: https://crystl.dev/docs/mcp-servers/