MCP-серверы

SOBA v0.4.0 работает как MCP-клиент: запускает локальные stdio MCP-серверы или подключается к remote Streamable HTTP endpoints, читает tools/list и публикует готовые tools в общий ToolRegistry.

Не входят в scope v0.4.0: SOBA как MCP-сервер, marketplace discovery, signed servers, deprecated HTTP+SSE как отдельный transport и security-решения на основе MCP tool annotations.

1. Поддерживаемые transports

2. Создать .soba/mcp.json

MCP-конфиг хранится в проекте:

mkdir -p .soba
touch .soba/mcp.json

Local stdio

{
  "version": 1,
  "servers": {
    "github": {
      "name": "GitHub MCP",
      "transport": "stdio",
      "command": "bunx",
      "args": ["some-github-mcp-server"],
      "cwd": ".",
      "env": {
        "GITHUB_TOKEN": "${ENV:GITHUB_TOKEN}"
      },
      "timeoutMs": 30000,
      "maxOutputBytes": 1048576,
      "trustMode": "normal",
      "enabled": true
    }
  }
}

Remote Streamable HTTP

{
  "version": 1,
  "servers": {
    "hosted-docs": {
      "name": "Hosted docs MCP",
      "transport": "streamableHttp",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "X-Workspace": "${ENV:MCP_WORKSPACE_ID}"
      },
      "auth": {
        "type": "none"
      },
      "timeoutMs": 30000,
      "maxOutputBytes": 1048576,
      "trustMode": "normal",
      "enabled": true
    }
  }
}

Context7-style hosted providers обычно дают один Streamable HTTP MCP endpoint для workspace/project. Используйте URL из dashboard или документации провайдера; SOBA docs не задают provider-specific endpoint.

servers может быть object-map или массивом. В object-map ключ становится server ID. SOBA также принимает mcpServers как compatibility alias; в одном файле используйте только один из этих ключей.

3. Remote auth

Поддержанные remote auth modes:

{ "type": "none" }

{ "type": "bearerEnv", "env": "REMOTE_MCP_BEARER_TOKEN" }

{ "type": "apiKeyEnv", "header": "X-API-Key", "env": "REMOTE_MCP_API_KEY" }

{ "type": "oauth" }

Некоторые remote MCP providers кладут credentials прямо в Streamable HTTP endpoint, например как API-key query parameter. Для такого варианта оставьте auth равным none и используйте env placeholder в url; token-like query params редактируются в diagnostics:

{
  "url": "https://mcp.example.com/mcp?apiKey=${ENV:REMOTE_MCP_API_KEY}",
  "auth": {
    "type": "none"
  }
}

Для bearerEnv и apiKeyEnv поле auth.env содержит имя env-переменной без ${ENV:...}. Placeholders ${ENV:...} также используются в headers и stdio env:

{
  "headers": {
    "X-Workspace": "${ENV:MCP_WORKSPACE_ID}"
  },
  "auth": {
    "type": "apiKeyEnv",
    "header": "X-API-Key",
    "env": "REMOTE_MCP_API_KEY"
  }
}

OAuth lifecycle:

/mcp auth status <server>
/mcp auth login <server>
/mcp auth logout <server>

Если remote server возвращает auth-required, /mcp status и /mcp auth status <server> показывают next action, обычно Run /mcp auth login <server>.

OAuth в SOBA покрывает discovery, PKCE browser flow, callback, token storage, refresh, logout и UX-команды /mcp auth .... Команды auth делегируют provider-specific интеграции через auth controller. Если controller не подключён для конкретного remote provider в текущей сборке, /mcp auth login <server> честно сообщает, что login flow недоступен.

Для первого production-подключения проще использовать bearerEnv или apiKeyEnv. OAuth выбирайте для provider integration, где controller уже подключает login flow и применение сохранённых bearer credentials к remote requests.

4. Trust boundary

Trust берётся только из локального .soba/mcp.json.

MCP server может прислать descriptions, JSON Schema, annotations, metadata и hints. SOBA использует эти данные для описания инструмента, но не для security decisions. Сервер не может сам понизить свой уровень доверия.

Рекомендуемая политика:

• safe — только read-only локальные tools без сетевых и файловых мутаций.
• normal — обычные dev tools, где подходит стандартный permission flow.
• dangerous — filesystem/API tools, запись на диск, внешние сервисы, credentials, remote mutations.

Remote auth headers, OAuth tokens, authorization codes и MCP-Session-Id редактируются в diagnostics и не должны попадать в docs или committed config.

Имена MCP tools в модели имеют OpenAI-compatible формат:

mcp_<server-id>_<tool-name>

Пример: mock-modern + echo → mcp_mock_modern_echo.

5. Команды /mcp

Команды выполняются внутри интерактивной сессии SOBA:

Tools регистрируются только для servers в состоянии ready.

6. Examples

Пошаговый remote setup:

• Remote MCP: пошаговый гайд

Verified local examples:

• docs/examples/mcp/mock-modern.json
• docs/examples/mcp/mock-legacy-paginated.json

Remote templates:

• docs/examples/mcp/remote-streamable-http.template.json
• docs/examples/mcp/remote-bearer-env.template.json
• docs/examples/mcp/remote-api-key-env.template.json
• docs/examples/mcp/remote-query-env.template.json
• docs/examples/mcp/remote-oauth.template.json

Remote templates выключены по умолчанию и используют https://mcp.example.com/mcp. Замените URL, экспортируйте нужные env vars, проверьте trustMode, затем поставьте "enabled": true.

Optional stdio template:

• docs/examples/mcp/filesystem-stdio.template.json

Он выключен по умолчанию, потому что зависит от npm-пакета в окружении пользователя.

7. Troubleshooting

8. Release validation

Для MCP docs/examples достаточно минимум:

bun test tests/core/mcp/config.test.ts
bun run lint
bunx tsc --noEmit
cd docs-site && bun run check

Перед релизными изменениями также выполняется сборка:

bun run build