MCP servers in Moon CLI

An MCP server adds tools to the agent: query a service, drive an app on your computer, read documentation. In Moon CLI, you add them from the agent, from the terminal or in a configuration file.

The connectors you have connected in Moon AI, including your Chat MCP servers and those of your organization, do not need to be added here: since Moon CLI 0.6.0, they come in on their own. See Moon AI connectors in Moon CLI.

Add a server from the agent#Link to the Add a server from the agent section

1. In the agent, type /mcp. The “Serveurs MCP” (MCP servers) window lists your “Serveurs configurés” (configured servers) with their status.
2. Under “Ajouter” (add), choose “Ajouter depuis le catalogue” (add from the catalog) or “Ajouter un serveur personnalisé (URL ou commande)” (add a custom server, URL or command).
3. If the server needs you to sign in to your account with that service, the sign-in page opens in your browser.
4. The server connects right away, without restarting Moon CLI.

Catalog#Link to the Catalog section

Custom server#Link to the Custom server section

1. Choose “Ajouter un serveur personnalisé (URL ou commande)” (add a custom server, URL or command).
2. Enter the “Nom du serveur MCP” (MCP server name): letters, digits and hyphens. The server’s tools will be called <name>_<tool>.
3. Enter the server’s address (https://…) or the command that starts it (for example npx -y @org/mcp-server).

Manage a server#Link to the Manage a server section

Select a server in the /mcp list:

Servers declared somewhere other than your personal configuration (in a project, for example) are marked “non modifiable ici” (cannot be changed here).

/mcps turns your servers on or off, and /status shows their status.

Signing in when the browser does not open#Link to the Signing in when the browser does not open section

On WSL, over SSH or on a server without a display, the sign-in window shows the link as soon as it is ready.

If the server does not respond, Moon CLI gives up after 30 seconds and says why. The window shows the elapsed time.

From the terminal#Link to the From the terminal section

moon mcp list
moon mcp add context7 --url https://mcp.context7.com/mcp
moon mcp add my-server -- npx -y mcp-package-name
moon mcp auth linear

Declaring a server in a file#Link to the Declaring a server in a file section

You can also declare a server under the mcp key of the agent configuration:

• in your personal configuration, ~/.config/moon/opencode.json (Windows: %USERPROFILE%\.config\moon\opencode.json), for all your projects. This is where /mcp writes;
• in a project’s opencode.json file, for that project only. Moon CLI only loads it after your approval: see A repository’s configuration.

A server that runs on your computer:

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "mcp-package-name"],
      "enabled": true
    }
  }
}

A remote server with a token read from an environment variable:

{
  "mcp": {
    "my-service": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer {env:MY_SERVICE_TOKEN}" },
      "enabled": true
    }
  }
}

Restart Moon CLI after editing the file, then type /mcp to check the server’s status. All keys: MCP servers in the configuration.

Moon CLI’s MCP servers are separate from those added in the web chat (“Connectors” › “MCP servers”, see MCP servers). Since Moon CLI 0.6.0, the web chat’s servers also come into the agent, with your other Moon AI connectors: see Moon AI connectors in Moon CLI.

Tool confirmation#Link to the Tool confirmation section

Each MCP server tool asks for your approval before it runs, like a command. You can choose to always allow it. In automatic approval mode, tools run without asking: see Permission modes.

To allow all of a server’s tools in advance in a project, add a rule to the project configuration:

{
  "permission": { "context7_*": "allow" }
}

Your data and MCP servers#Link to the Your data and MCP servers section

• What a tool returns goes through Moon Blur before it is sent to the model, like the rest of the conversation.
• What a tool receives contains the real values: Moon CLI puts masked values back in clear text before the call, so that the tool works. With Moon Guard on, a call that would send a real secret to an MCP tool is blocked.
• A local server runs on your machine with your permissions. Only add servers whose publisher you know.
• A remote server receives whatever the agent sends it. Check what you allow it to do.

See also#Link to the See also section

• Configuration
• Moon Guard
• Command reference