@42clouds/mcp-ms

MCP server for 42Clouds MS API — 1C microservices, platform permissions, delimiters, resources.

Built on the Model Context Protocol. Exposes the entire 42Clouds MS API as a single api tool with dynamic swagger-based operation discovery, JWT auto-refresh, and approval gates for dangerous operations.

Quick Start

Before anything else you need two things from the user:

1. 42Clouds personal account credentials (login + password for the 42Clouds LK) — the server cannot authenticate without them.
2. Which stand to connect to — production (ms) or one of the dev/beta stands.

export CLOUDS42_USER=your-login
export CLOUDS42_PASSWORD=your-password
export CLOUDS42_MS_URL=https://ms.42clouds.com   # production — the default

# No install needed — just run with npx
npx -y @42clouds/mcp-ms

Credentials are per stand. A login that works on ms will not necessarily work on dev-area-02. Ask the user for the credentials of the stand they named.

Stands

42Clouds runs on several stands. Setting CLOUDS42_MS_URL is enough — the OID provider and the swagger endpoint are derived from it.

| Stand | MS API (CLOUDS42_MS_URL) | OID provider | Matching Core API | |-------|----------------------------|--------------|-------------------| | Production (default) | https://ms.42clouds.com | https://provider.42clouds.com | https://core.42clouds.com | | Beta | https://beta-ms.42clouds.com | same as MS API | https://betacore.42clouds.com | | Dev 1 | https://dev-area-01.42clouds.com | same as MS API | https://dev1core.42clouds.com | | Dev 2 | https://dev-area-02.42clouds.com | same as MS API | https://dev2core.42clouds.com | | Dev 3 | https://dev-area-03.42clouds.com | same as MS API | https://dev3core.42clouds.com | | Dev 4 | https://dev-area-04.42clouds.com | same as MS API | https://dev4core.42clouds.com | | Dev 6 | https://dev-area-06.42clouds.com | same as MS API | https://dev6core.42clouds.com |

Production is the exception: it serves OID from a dedicated host (provider.42clouds.com), not from ms.42clouds.com. Every other stand serves it from the MS host itself. The server handles this for you.

# Production (default — applies when CLOUDS42_MS_URL is unset)
export CLOUDS42_MS_URL=https://ms.42clouds.com

# Beta
export CLOUDS42_MS_URL=https://beta-ms.42clouds.com

# Dev 2 — provider and swagger follow automatically
export CLOUDS42_MS_URL=https://dev-area-02.42clouds.com

If you run @42clouds/mcp-core alongside this server, point both at the same stand — use the Core API column above.

⚠️ The default is production. Operations run against live data. If the user has not named a stand, ask before connecting.

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CLOUDS42_USER | yes* | — | 42Clouds login | | CLOUDS42_PASSWORD | yes* | — | 42Clouds password | | CLOUDS42_MS_URL | no | https://ms.42clouds.com | MS API base URL — see Stands | | CLOUDS42_MS_SWAGGER_URL | no | derived from CLOUDS42_MS_URL | Swagger JSON URL | | CLOUDS42_MS_PROVIDER_URL | no | derived from CLOUDS42_MS_URL | OID2 provider URL for JWT authentication | | CLOUDS42_JWT | no* | — | Existing JWT token (alternative to user/password) | | CLOUDS42_REFRESH_TOKEN | no | — | Existing refresh token |

* Either CLOUDS42_USER+CLOUDS42_PASSWORD or CLOUDS42_JWT is required.

Swagger is built from the API host as {CLOUDS42_MS_URL}/ms-help/hs/help/openApi.json?template=PL_RESTful_OpenAPI. The OID provider is {CLOUDS42_MS_URL}/oid/hs/oid2op on every stand except production, which uses https://provider.42clouds.com/oid/hs/oid2op. Override them only for a host that is not in the Stands table (the server prints a warning in that case).

CLI Options

npx -y @42clouds/mcp-ms --swagger /path/to/local-swagger.json

Use --swagger for offline mode — loads a local OpenAPI spec instead of downloading from the API.

Deprecated Variables

BETACORE_* variables are still supported but deprecated. Migrate to CLOUDS42_*.

Client Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "42clouds-ms": {
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-ms"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_MS_URL": "https://ms.42clouds.com"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "42clouds-ms": {
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-ms"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_MS_URL": "https://ms.42clouds.com"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "42clouds-ms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-ms"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_MS_URL": "https://ms.42clouds.com"
      }
    }
  }
}

OpenClaw

Add to openclaw.json → mcp.servers:

{
  "42clouds-ms": {
    "command": "npx",
    "args": ["-y", "@42clouds/mcp-ms"],
    "env": {
      "CLOUDS42_USER": "your-login",
      "CLOUDS42_PASSWORD": "your-password",
      "CLOUDS42_MS_URL": "https://ms.42clouds.com"
    }
  }
}

Using Both Core and MS

{
  "mcpServers": {
    "42clouds-core": {
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-core"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_API_URL": "https://core.42clouds.com"
      }
    },
    "42clouds-ms": {
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-ms"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_MS_URL": "https://ms.42clouds.com"
      }
    }
  }
}

Keep the two on the same stand — core + ms, betacore + beta-ms, dev2core + dev-area-02, and so on (see Stands).

For AI Agents

This server is designed to be easily used by AI agents and LLMs. Here's what you need to know:

Before you connect

If you are setting this server up for a user, you need two answers from them — neither can be guessed:

1. "Which stand should I connect to?" — production (ms, the default) or a dev/beta stand. List the options from Stands. Do not silently fall back to production: it operates on live data.
2. "What are your 42Clouds personal account credentials for that stand?" — login and password. These are per stand and are not interchangeable.

Then set CLOUDS42_USER, CLOUDS42_PASSWORD, and CLOUDS42_MS_URL. The OID provider and swagger endpoint are derived from it — leave CLOUDS42_MS_PROVIDER_URL and CLOUDS42_MS_SWAGGER_URL unset.

On startup the server prints the stand it is using to stderr:

[mcp-ms] API: https://ms.42clouds.com
[mcp-ms] OID provider: https://provider.42clouds.com/oid/hs/oid2op

Check that line before running anything destructive — it is the only confirmation of which environment you are pointed at.

Calling the API

One tool — api — calls any 42Clouds MS endpoint by operationId. No need to guess URLs or HTTP methods.

api(tag="Resources", operationId="Resources_GetList", queryParams={take: 10})
api(tag="Delimiters", operationId="Delimiters_GetInfo", pathParams={id: "GUID"})
api(operationId="Applications_GetList", queryParams={"filter.accountId": "GUID"})

Discovery workflow:

1. Read clouds42-ms://domains to see all available API domains (e.g. Resources, Delimiters, Applications)
2. Read clouds42-ms://operations/Resources to see all operations in a domain
3. Read clouds42-ms://search/resource to find operations by keyword
4. Call api(operationId="...") with the operationId you found

Important rules:

• Always specify tag when you know which domain you need — it validates the operationId
• For operations on other accounts, pass contextAccountId="GUID"
• Destructive operations require confirmation: first call returns requestId, re-call with confirm: true and identical arguments — a requestId is bound to the exact call it was issued for
• Query params with dots (e.g. filter.accountId) must be passed as-is: queryParams={"filter.accountId": "GUID"}
• Do NOT shorten filter names — accountId ≠ filter.accountId. The API silently ignores unknown params
• For POST/PUT/PATCH, provide body with the request payload
• After each call, the response includes available params for the next step

Available domains (24 total): Accounts, AdvertisingTags, ApplicationBackups, ApplicationUsers, Applications, Configurations, Core, Files, Market filters, Market services, Market slides, Permissions, Registration, Security, ServiceProposals, ServiceVersions, Services, Sessions, SsoAccounts, SuppliedDataProcessors, and more.

Examples

List resources:

api(operationId="Resources_GetList", queryParams={take: 5})
→ { status: 200, data: [{ id: "...", name: "My Resource", type: "..." }, ...] }

Get delimiter info:

api(tag="Delimiters", operationId="AcDbDelimiters_GetDelimiter", pathParams={id: "CB9E6F28-D9A2-4C8B-B7A2-..."})
→ { status: 200, data: { id: "...", databaseId: "...", delimiter: {...} } }

Search for service operations:

clouds42-ms://search/service
→ [{ operationId: "Services_GetList", tag: "Services", method: "GET" }, ...]

Dangerous operation (delete) — requires confirmation:

api(operationId="Applications_Delete", pathParams={id: "123"})
→ { status: 403, message: "Confirmation required", requestId: "abc-123" }

api(operationId="Applications_Delete", pathParams={id: "123"}, confirm: true, requestId: "abc-123")
→ { status: 200, data: null }

How It Works

Resource Discovery

• clouds42-ms://info — API name, version, statistics
• clouds42-ms://domains — all API domains with operation counts
• clouds42-ms://operations/{tag} — operations in a domain
• clouds42-ms://search/{query} — fuzzy search across all operations

Safety Features

• Approval gate — every DELETE, every Admin endpoint, and mutating operations whose name implies destruction (cancel, reset, restore, block, revoke…) require explicit confirmation. The confirmation is single-use and bound to the operation, its arguments and the account context
• Parameter hints — after each call, available query/path/body params are listed
• JWT auto-refresh — tokens are refreshed automatically before expiry
• Retry logic — automatic retry on network errors and 5xx responses (up to 2 retries)

⚠️ Security: stdio-only

This MCP server must only run as a stdio subprocess (Phase 1). It does not support Streamable http transport.

• Credentials (JWT, refresh tokens, passwords) are read from environment variables and held in memory
• There is no authentication on the MCP transport layer — anyone with network access could call the API
• The server will refuse to start if MCP_STREAMABLE_HTTP, MCP_HTTP_PORT, or MCP_HOST environment variables are set
• Never expose this server on a network — it must always be a local subprocess of the AI agent

If you need remote deployment in the future, it must include transport-layer authentication (API key, TLS, etc.) — this is planned for a future Phase 2 release.

Swagger Auto-Update

The OpenAPI spec is downloaded at startup and refreshed every 6 hours. Downloaded specs are cached in ~/.cache/42clouds-mcp/ for offline fallback.

AI Agent Instructions Snippet

Add this to your .cursorrules, .github/copilot-instructions.md, or project system prompt:

When working with 42Clouds MS API, use the mcp-ms tool "api":
- Setup: ask the user which stand to use (prod ms / beta-ms / dev-area-01..06) and for
  their 42Clouds personal account login+password for THAT stand. Never assume — the
  default is production, which touches live data.
- Set CLOUDS42_MS_URL to the chosen stand; provider and swagger are derived from it
- Discover: read clouds42-ms://domains, then clouds42-ms://operations/{tag}
- Search: read clouds42-ms://search/{query}
- Call: api(tag="Domain", operationId="Operation_Name", queryParams={...}, pathParams={...}, body={...})
- Params with dots like filter.accountId must be passed as-is in queryParams
- Destructive operations need confirm:true after getting requestId, with identical arguments
- For other accounts: add contextAccountId="GUID"

Related

• @42clouds/mcp-core — MCP server for 42Clouds Core API (platform management, billing)
• 42Clouds — Cloud platform for 1C

License

MIT