# Troubleshooting

Due to the emerging nature of the MCP Specification and differences in how
various LLM providers and client applications implement it, you may encounter
issues when hosting and using MCP servers with Gram. This troubleshooting guide
addresses common problems and provides solutions to help you resolve them
quickly.

### Helpful resources

The following external resources provide additional context and information
about MCP, and may be helpful when troubleshooting issues:

- <a href="https://modelcontextprotocol.io/specification/latest"
  target="_blank" rel="noreferrer">MCP Specification:</a> The
  official documentation for the Model Context Protocol (MCP).
- <a href="https://modelcontextprotocol.io/clients" target="_blank" rel="noreferrer">MCP client
  feature support matrix:</a> A list of well-known LLM clients and their level
  of MCP support. _Many LLM clients do not support all of Gram's MCP server
  features_.

## Issues with MCP remote and Node.js environments

Some LLM clients, such as **Claude**, are not yet able to connect to remote MCP
servers natively. To overcome this, you can use the `mcp-remote` CLI tool to proxy
requests from an LLM client to hosted MCP servers:

```json filename="mcp-remote"
{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}
```

Since version `0.1.26` of the `mcp-remote` package, some users have <a
href="https://github.com/geelen/mcp-remote/issues/156"
target="blank">reported</a> servers failing to start, with `Client transport
closed` appearing in client logs.

This is typically due to the LLM client attempting to use an older version of
Node.js than required to execute `mcp-remote`.

## Solutions

### Use Node.js 20 or higher (recommended)

Ensure that you're using Node.js version 20 or higher. If you run into issues, check the Claude Desktop logs to see which Node.js version it is selecting. Claude Desktop has at times shown a tendency to select the lowest version of Node.js it can find on your machine, regardless of the default Node.js version. Instructions for
installing and managing Node.js versions can be found on the <a
href="https://nodejs.org/en/download/" target="_blank" rel="noreferrer">official Node.js
website</a>.

### Pin `mcp-remote` to version `0.1.25`

If you're unable to install or change to a compatible version of Node.js, you can pin the
`mcp-remote` package to version `0.1.25` in your MCP configuration:

```json ins="@0.1.25"
{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.25",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}
```

## Getting support

If you're encountering a persistent issue that isn't covered in this
troubleshooting guide, please reach out to Gram support via the in-app chat, or
join our <a href="https://go.speakeasy.com/slack" target="_blank" rel="noreferrer">Slack
community</a> to get help!