Publishing and Connecting to Claude, Cursor, and VS Code

Цель дистрибуции stdio-сервера — одна команда у пользователя: npx -y @acme/orders-mcp. Для этого пакет должен быть исполняемым:

{
  "name": "@acme/orders-mcp",
  "version": "1.0.0",
  "type": "module",
  "bin": { "orders-mcp": "dist/index.js" },
  "files": ["dist"],
  "scripts": {
    "build": "tsc && chmod +x dist/index.js",
    "prepublishOnly": "npm run build"
  }
}

Три обязательных элемента. Первое — shebang первой строкой src/index.ts, чтобы ОС знала, чем исполнять файл:

#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

Второе — поле bin: по нему npm создаст исполняемую ссылку, а npx сможет запустить пакет без установки. Третье — files: ["dist"], чтобы в пакет не уехали исходники, тесты и .env (проверьте содержимое через npm pack --dry-run — этот же артефакт можно установить локально и проверить до публикации: npm install -g ./acme-orders-mcp-1.0.0.tgz).

Версионируйте по SemVer с точки зрения контракта инструментов: изменение схемы аргументов или удаление инструмента — это major, новый инструмент — minor, правка описания — patch. Пользователи с npx -y получают последнюю версию при каждом запуске, поэтому сломанный minor разлетится мгновенно.

В Claude Code сервер добавляется одной командой; всё после -- — команда запуска:

claude mcp add orders -- npx -y @acme/orders-mcp

# С передачей секрета:
claude mcp add orders --env PRODUCT_API_KEY=sk-prod-... -- npx -y @acme/orders-mcp

# Удалённый HTTP-сервер:
claude mcp add --transport http orders-remote https://mcp.acme.dev/mcp

У Claude Code три области видимости конфигурации: local (по умолчанию, только вы и только этот проект), user (все ваши проекты) и project — файл .mcp.json в корне репозитория, который коммитится в git и раздаёт сервер всей команде:

claude mcp add orders --scope project -- npx -y @acme/orders-mcp

Проверка — команда /mcp внутри сессии: покажет статус подключения, список инструментов и ошибки.

Claude Desktop настраивается файлом claude_desktop_config.json (на macOS — в ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "orders": {
      "command": "npx",
      "args": ["-y", "@acme/orders-mcp"],
      "env": { "PRODUCT_API_KEY": "sk-prod-..." }
    }
  }
}

Два вечных источника тикетов поддержки: конфиг вступает в силу только после полного перезапуска приложения, а невалидный JSON (лишняя запятая) молча ломает загрузку всех серверов. Кладите готовый блок конфигурации в README пакета — пользователи копируют его чаще, чем читают инструкцию.

Cursor использует тот же формат mcpServers: глобально — ~/.cursor/mcp.json, на проект — .cursor/mcp.json в корне репозитория:

{
  "mcpServers": {
    "orders": {
      "command": "npx",
      "args": ["-y", "@acme/orders-mcp"],
      "env": { "PRODUCT_API_KEY": "sk-prod-..." }
    }
  }
}

Статус виден в Settings → MCP; там же сервер можно перезапустить после обновления пакета.

VS Code (GitHub Copilot agent mode) читает .vscode/mcp.json с другим форматом — ключ servers и явный type. Зато есть механизм inputs, решающий проблему секретов в коммитируемом файле:

{
  "inputs": [
    {
      "id": "product-api-key",
      "type": "promptString",
      "description": "Product API key",
      "password": true
    }
  ],
  "servers": {
    "orders": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@acme/orders-mcp"],
      "env": { "PRODUCT_API_KEY": "${input:product-api-key}" }
    }
  }
}

VS Code запросит значение при первом запуске и сохранит его в защищённом хранилище — файл в git остаётся чистым. Это правильный паттерн для командных репозиториев: конфигурация коммитится, секреты — никогда.

Итого у вашего README три блока подключения: Claude (команда + JSON), Cursor (JSON), VS Code (JSON с inputs). Проверяйте все три на живых клиентах перед релизом — форматы похожи ровно настолько, чтобы перепутать.

Когда сервер — часть продукта, дистрибуция через npm неудобна: обновления у пользователей, секреты на их машинах, нет централизованного контроля. Решение — удалённый сервер на Streamable HTTP: один URL, обновления мгновенны, авторизация по OAuth из урока 4.

С тем же McpServer меняется только транспортный слой — например, на Express:

import express from 'express';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // stateless-режим
  });
  res.on('close', () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);

Stateless-режим (без session id) — самый простой для горизонтального масштабирования: каждый запрос самодостаточен, подойдёт любой балансировщик. Stateful-режим с sessionIdGenerator и заголовком Mcp-Session-Id нужен, когда сервер держит состояние между вызовами или шлёт notifications — тогда потребуется sticky-маршрутизация или общее хранилище сессий.

Подключение у пользователей — одной строкой: claude mcp add --transport http orders https://mcp.acme.dev/mcp; Cursor и VS Code принимают "url" вместо "command" в тех же конфигах. Для публичного каталога добавьте сервер в официальный MCP Registry — клиенты постепенно учатся ставить серверы прямо из него.

Правило выбора: инструмент для разработчиков, работающий с локальными файлами, — npm + stdio; сервис вашего продукта для всех пользователей — удалённый HTTP с OAuth.