mcp-remote

Подключите MCP-клиент, который поддерживает только локальные (stdio) серверы, к удалённому MCP-серверу с поддержкой аутентификации:

Примечание: это работающее доказательство концепции, но его следует считать экспериментальным.

Зачем это нужно?

На данный момент большинство MCP-серверов в дикой природе устанавливаются локально с использованием транспорта stdio. У этого есть некоторые преимущества: и клиент, и сервер могут неявно доверять друг другу, поскольку пользователь предоставил им обоим разрешение на запуск. Добавление секретов, таких как API-ключи, можно выполнять с помощью переменных окружения, и они никогда не покидают вашу машину. А использование npx и uvx также позволило пользователям избежать явных шагов установки.

Но есть причина, по которой большинство программного обеспечения, которое можно было перенести в веб, было перенесено: гораздо проще находить и исправлять ошибки и итерировать новые функции, когда можно развернуть обновления для всех пользователей одним развёртыванием.

С последней спецификацией авторизации MCP у нас теперь есть безопасный способ делиться нашими MCP-серверами с миром без запуска кода на ноутбуках пользователей. Или, по крайней мере, так было бы, если бы все популярные MCP-клиенты уже поддерживали это. Большинство из них поддерживают только stdio, а те, которые поддерживают HTTP+SSE, пока не поддерживают требуемые потоки OAuth.

Вот тут и появляется mcp-remote. Как только ваш выбранный MCP-клиент начнёт поддерживать удалённые авторизованные серверы, вы сможете его удалить. А до тех пор вставьте эту однострочную команду и настраивайтесь под нужные MCP-клиенты!

Использование

Все самые популярные MCP-клиенты (Claude Desktop, Cursor и Windsurf) используют следующий формат конфигурации:

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

Пользовательские заголовки

Чтобы обойти аутентификацию или отправлять пользовательские заголовки во всех запросах к вашему удалённому серверу, передайте аргументы командной строки --header:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

Примечание: В Cursor и Claude Desktop (Windows) есть ошибка: пробелы внутри args не экранируются при вызове npx, что приводит к искажению этих значений. Вы можете обойти это, используя:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

Флаги

• Если npx выдаёт ошибки, попробуйте добавить -y в качестве первого аргумента для автоматического принятия установки пакета mcp-remote.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• Чтобы заставить npx всегда проверять обновлённую версию mcp-remote, добавьте флаг @latest:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• Чтобы изменить порт, на котором mcp-remote ожидает перенаправления OAuth (по умолчанию 3334), добавьте дополнительный аргумент после URL сервера. Обратите внимание: независимо от указанного порта, если он недоступен, будет выбран случайный свободный порт.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• Чтобы изменить хост, который mcp-remote регистрирует как URL обратного вызова OAuth (по умолчанию localhost), добавьте флаг --host.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• Чтобы разрешить HTTP-соединения в доверенных частных сетях, добавьте флаг --allow-http. Примечание: это следует использовать только в защищённых частных сетях, где трафик не может быть перехвачен.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• Чтобы включить подробные журналы отладки, добавьте флаг --debug. Это будет записывать подробные логи в ~/.mcp-auth/{server_hash}_debug.log с временными метками и детальной информацией о процессе аутентификации, соединениях и обновлении токенов.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• Чтобы включить исходящий HTTP(S)-прокси для mcp-remote, добавьте флаг --enable-proxy. При включении mcp-remote будет использовать настройки прокси из стандартных переменных окружения (например, HTTP_PROXY, HTTPS_PROXY и NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• Чтобы игнорировать определённые инструменты на удалённом сервере, добавьте флаг --ignore-tool. Это отфильтрует инструменты, соответствующие указанным шаблонам, из ответов tools/list и заблокирует запросы tools/call. Поддерживает шаблоны с подстановочными знаками *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

Вы можете указать несколько флагов --ignore-tool, чтобы игнорировать разные шаблоны. Примеры:

• delete* — игнорирует все инструменты, начинающиеся с "delete" (например, deleteTask, deleteUser)
• *account — игнорирует все инструменты, заканчивающиеся на "account" (например, getAccount, updateAccount)
• exactTool — игнорирует только инструмент с точным именем "exactTool"

• Чтобы изменить таймаут для обратного вызова OAuth (по умолчанию 30 секунд), добавьте флаг --auth-timeout со значением в секундах. Это полезно, если процесс аутентификации на стороне сервера занимает много времени.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

Стратегии транспорта

MCP Remote поддерживает различные стратегии транспорта при подключении к MCP-серверу. Это позволяет вам контролировать, будет ли он использовать транспорт Server-Sent Events (SSE) или HTTP, и в каком порядке их пробовать.

Укажите стратегию транспорта с помощью флага --transport:

npx mcp-remote https://example.remote/server --transport sse-only

Доступные стратегии:

• http-first (по умолчанию): сначала пробует HTTP-транспорт, переключается на SSE, если HTTP завершается ошибкой 404
• sse-first: сначала пробует SSE-транспорт, переключается на HTTP, если SSE завершается ошибкой 405
• http-only: использует только HTTP-транспорт, завершается ошибкой, если сервер его не поддерживает
• sse-only: использует только SSE-транспорт, завершается ошибкой, если сервер его не поддерживает

Статические метаданные клиента OAuth

MCP Remote поддерживает предоставление статических метаданных клиента OAuth вместо использования значений по умолчанию mcp-remote. Это полезно при подключении к OAuth-серверам, которые ожидают определённые идентификаторы клиента/программного обеспечения или области (scopes).

Предоставьте метаданные клиента в виде JSON-строки или пути к файлу с префиксом @ с помощью флага --static-oauth-client-metadata: