@42clouds/mcp-core

MCP server for 42Clouds Core API — cloud platform management, billing, accounts, databases, users.

Built on the Model Context Protocol. Exposes the entire 42Clouds Core 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 (core) or one of the dev/beta stands.

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

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

Credentials are per stand. A login that works on core will not necessarily work on dev2core. Ask the user for the credentials of the stand they named.

Stands

Every Core API host has its own OpenID (OID) provider that issues the JWT. The two must match — a token issued by the production provider is rejected by a dev Core API, and vice versa.

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

You normally only set CLOUDS42_API_URL. The matching OID provider is derived from the table above automatically. Set CLOUDS42_PROVIDER_URL only for a host that is not listed (the server prints a warning in that case).

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

# Beta
export CLOUDS42_API_URL=https://betacore.42clouds.com

# Dev 2 — provider becomes https://dev-area-02.42clouds.com/oid/hs/oid2op
export CLOUDS42_API_URL=https://dev2core.42clouds.com

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

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CLOUDS42_USER | yes* | — | 42Clouds personal account login (per stand) | | CLOUDS42_PASSWORD | yes* | — | 42Clouds personal account password | | CLOUDS42_API_URL | no | https://core.42clouds.com | Core API base URL — see Stands | | CLOUDS42_PROVIDER_URL | no | derived from CLOUDS42_API_URL | OID2 provider URL for JWT authentication | | CLOUDS42_SWAGGER_URL | no | v1+v2 auto-derived from API_URL | Swagger JSON URL(s), comma-separated for multiple | | 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 URLs are auto-derived from API URL (/swagger/v1/ + /swagger/v2/).

CLI Options

npx -y @42clouds/mcp-core --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-core": {
      "command": "npx",
      "args": ["-y", "@42clouds/mcp-core"],
      "env": {
        "CLOUDS42_USER": "your-login",
        "CLOUDS42_PASSWORD": "your-password",
        "CLOUDS42_API_URL": "https://core.42clouds.com"
      }
    }
  }
}

Cursor

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

{
  "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"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

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

OpenClaw

Add to openclaw.json → mcp.servers:

{
  "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"
    }
  }
}

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 (core, the default) or a dev/beta stand. List the options from Stands. Do not silently fall back to production: it operates on live accounts and billing.
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_API_URL for the chosen stand. The OID provider is derived automatically — leave CLOUDS42_PROVIDER_URL unset unless the host is not in the table.

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

[mcp-core] API: https://core.42clouds.com
[mcp-core] 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 Core endpoint by operationId. No need to guess URLs or HTTP methods.

api(tag="Users", operationId="Users_GetList", queryParams={take: 10})
api(tag="Accounts", operationId="Accounts_GetAccount", pathParams={id: "GUID"})
api(operationId="AccountDatabases_GetList", queryParams={"filter.accountId": "GUID"})

Discovery workflow:

1. Read clouds42-core://domains to see all available API domains (e.g. Users, Accounts, BillingService)
2. Read clouds42-core://operations/Users to see all operations in a domain
3. Read clouds42-core://search/invoice 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 (105 total): Partners, BillingService, AccountUsers, Account, AccountDatabases, Marketing, BillingAccounts, Articles, MyDisk, SupplierReference, CloudCore, CoreWorkers, Agents, Agencies, CloudServices, Configurations1C, Arm, and 80+ more.

Examples

List users:

api(operationId="Users_GetList", queryParams={take: 5})
→ { status: 200, data: [{ id: "...", login: "admin", email: "..." }, ...] }

Get account by ID:

api(tag="Account", operationId="Accounts_GetAccount", pathParams={id: "CB9E6F28-D9A2-4C8B-B7A2-..."})
→ { status: 200, data: { id: "...", name: "My Account", status: "Active" } }

Search for invoice operations:

clouds42-core://search/invoice
→ [{ operationId: "InvoiceCreation_CreateInvoice", tag: "InvoiceCreation", method: "POST" }, ...]

Dangerous operation (delete) — requires confirmation:

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

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

How It Works

Resource Discovery

• clouds42-core://info — API name, version, statistics
• clouds42-core://domains — all API domains with operation counts
• clouds42-core://operations/{tag} — operations in a domain
• clouds42-core://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 Core API, use the mcp-core tool "api":
- Setup: ask the user which stand to use (prod core / beta / dev1-dev6) and for their
  42Clouds personal account login+password for THAT stand. Never assume — the default
  is production, which touches live accounts and billing.
- Set CLOUDS42_API_URL to the chosen stand; the OID provider is derived automatically
- Discover: read clouds42-core://domains, then clouds42-core://operations/{tag}
- Search: read clouds42-core://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-ms — MCP server for 42Clouds MS API (1C microservices)
• 42Clouds — Cloud platform for 1C

License

MIT