@centrali-io/centrali-mcp 4.5.2 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +34 -11
  2. package/dist/index.js +23 -7
  3. package/package.json +1 -1
  4. package/src/index.ts +26 -7
package/README.md CHANGED
@@ -4,11 +4,30 @@ MCP (Model Context Protocol) server for the Centrali platform. Lets AI assistant
4
4
 
5
5
  > **Full documentation:** [docs.centrali.io](https://docs.centrali.io) — SDK guide, API reference, compute functions, orchestrations, and more.
6
6
 
7
- Built on `@centrali-io/centrali-sdk` v4.4.7. Authenticates via service account client credentials.
7
+ ## Two ways to connect
8
8
 
9
- ## Setup
9
+ ### Option 1: Hosted MCP Server (recommended)
10
10
 
11
- Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
11
+ The easiest way to connect any AI client to Centrali. Add a single URL — authentication happens in the browser via OAuth.
12
+
13
+ **Claude Desktop / Claude Code / Cursor:**
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "centrali": {
19
+ "type": "url",
20
+ "url": "https://mcp.centrali.io"
21
+ }
22
+ }
23
+ }
24
+ ```
25
+
26
+ On first use, your AI client opens a browser for login and workspace selection. No client ID, secret, or workspace slug needed.
27
+
28
+ ### Option 2: Stdio with Service Account (CI/automation)
29
+
30
+ For headless environments (CI pipelines, automation scripts, cron jobs) where browser login isn't possible. Uses service account credentials with RBAC permissions.
12
31
 
13
32
  ```json
14
33
  {
@@ -27,14 +46,22 @@ Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
27
46
  }
28
47
  ```
29
48
 
30
- ### Environment Variables
49
+ ### Migrating from OAuth stdio to hosted
50
+
51
+ If you were previously using `CENTRALI_OAUTH_CLIENT_ID` with the stdio package, switch to the hosted URL:
52
+
53
+ 1. Remove the old `command`/`args`/`env` configuration
54
+ 2. Replace with: `{ "type": "url", "url": "https://mcp.centrali.io" }`
55
+ 3. On next connection, authenticate in the browser
56
+
57
+ ### Environment Variables (stdio mode only)
31
58
 
32
59
  | Variable | Required | Description |
33
60
  |----------|----------|-------------|
34
61
  | `CENTRALI_URL` | Yes | Centrali instance URL (e.g., `https://centrali.io`) |
62
+ | `CENTRALI_WORKSPACE` | Yes | Workspace slug to operate in |
35
63
  | `CENTRALI_CLIENT_ID` | Yes | Service account client ID |
36
64
  | `CENTRALI_CLIENT_SECRET` | Yes | Service account client secret |
37
- | `CENTRALI_WORKSPACE` | Yes | Workspace slug to operate in |
38
65
 
39
66
  ### Service Account Permissions
40
67
 
@@ -42,16 +69,12 @@ A freshly created service account **has no permissions by default**. You must as
42
69
 
43
70
  **Quickest setup — full admin access:**
44
71
 
45
- 1. In the Console, go to **Settings → Service Accounts**
72
+ 1. In the Console, go to **Settings > Service Accounts**
46
73
  2. Create your service account and save the client secret
47
74
  3. Open the service account, go to the **Groups** tab
48
75
  4. Add it to the **workspace_administrators** group
49
76
 
50
- This gives the MCP server full access to all workspace resources.
51
-
52
- **Least-privilege setup — custom permissions:**
53
-
54
- If you only want the MCP to manage specific resources (e.g., collections and records but not billing), create a custom group with a policy scoped to the resources you need, then add the service account to that group. See the [Policies and Permissions guide](https://docs.centrali.io/authentication/policies-and-permissions/) for details.
77
+ **Least-privilege setup:** Create a custom group with a policy scoped to the resources you need. See the [Policies and Permissions guide](https://docs.centrali.io/authentication/policies-and-permissions/) for details.
55
78
 
56
79
  ## Getting Started
57
80
 
package/dist/index.js CHANGED
@@ -36,16 +36,32 @@ function getRequiredEnv(name) {
36
36
  }
37
37
  function main() {
38
38
  return __awaiter(this, void 0, void 0, function* () {
39
+ // ── Migration check ──────────────────────────────────────────
40
+ // Browser OAuth and client_credentials flows have moved to the hosted MCP server.
41
+ // Detect old env vars and guide users to the new setup.
42
+ if (process.env.CENTRALI_OAUTH_CLIENT_ID) {
43
+ console.error("\n" +
44
+ "══════════════════════════════════════════════════════════════\n" +
45
+ " Browser OAuth has moved to the hosted MCP server.\n" +
46
+ "\n" +
47
+ " Replace this stdio configuration with a single URL:\n" +
48
+ "\n" +
49
+ ' { "type": "url", "url": "https://mcp.centrali.io" }\n' +
50
+ "\n" +
51
+ " Your AI client will open a browser for login automatically.\n" +
52
+ " No client ID, secret, or workspace slug needed.\n" +
53
+ "\n" +
54
+ " Guide: https://docs.centrali.io/sdk/mcp/\n" +
55
+ "══════════════════════════════════════════════════════════════\n");
56
+ process.exit(0);
57
+ }
58
+ // ── Service account mode (the only mode for stdio) ───────────
39
59
  const baseUrl = getRequiredEnv("CENTRALI_URL");
60
+ const workspaceId = getRequiredEnv("CENTRALI_WORKSPACE");
40
61
  const clientId = getRequiredEnv("CENTRALI_CLIENT_ID");
41
62
  const clientSecret = getRequiredEnv("CENTRALI_CLIENT_SECRET");
42
- const workspaceId = getRequiredEnv("CENTRALI_WORKSPACE");
43
- const sdk = new centrali_sdk_1.CentraliSDK({
44
- baseUrl,
45
- workspaceId,
46
- clientId,
47
- clientSecret,
48
- });
63
+ const sdk = new centrali_sdk_1.CentraliSDK({ baseUrl, workspaceId, clientId, clientSecret });
64
+ console.error(`[centrali-mcp] Ready — service account (client: ${clientId})`);
49
65
  const server = new mcp_js_1.McpServer({
50
66
  name: "centrali",
51
67
  version: "1.0.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@centrali-io/centrali-mcp",
3
- "version": "4.5.2",
3
+ "version": "5.0.0",
4
4
  "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
5
5
  "main": "dist/index.js",
6
6
  "type": "commonjs",
package/src/index.ts CHANGED
@@ -27,17 +27,36 @@ function getRequiredEnv(name: string): string {
27
27
  }
28
28
 
29
29
  async function main() {
30
+ // ── Migration check ──────────────────────────────────────────
31
+ // Browser OAuth and client_credentials flows have moved to the hosted MCP server.
32
+ // Detect old env vars and guide users to the new setup.
33
+ if (process.env.CENTRALI_OAUTH_CLIENT_ID) {
34
+ console.error(
35
+ "\n" +
36
+ "══════════════════════════════════════════════════════════════\n" +
37
+ " Browser OAuth has moved to the hosted MCP server.\n" +
38
+ "\n" +
39
+ " Replace this stdio configuration with a single URL:\n" +
40
+ "\n" +
41
+ ' { "type": "url", "url": "https://mcp.centrali.io" }\n' +
42
+ "\n" +
43
+ " Your AI client will open a browser for login automatically.\n" +
44
+ " No client ID, secret, or workspace slug needed.\n" +
45
+ "\n" +
46
+ " Guide: https://docs.centrali.io/sdk/mcp/\n" +
47
+ "══════════════════════════════════════════════════════════════\n"
48
+ );
49
+ process.exit(0);
50
+ }
51
+
52
+ // ── Service account mode (the only mode for stdio) ───────────
30
53
  const baseUrl = getRequiredEnv("CENTRALI_URL");
54
+ const workspaceId = getRequiredEnv("CENTRALI_WORKSPACE");
31
55
  const clientId = getRequiredEnv("CENTRALI_CLIENT_ID");
32
56
  const clientSecret = getRequiredEnv("CENTRALI_CLIENT_SECRET");
33
- const workspaceId = getRequiredEnv("CENTRALI_WORKSPACE");
34
57
 
35
- const sdk = new CentraliSDK({
36
- baseUrl,
37
- workspaceId,
38
- clientId,
39
- clientSecret,
40
- });
58
+ const sdk = new CentraliSDK({ baseUrl, workspaceId, clientId, clientSecret });
59
+ console.error(`[centrali-mcp] Ready — service account (client: ${clientId})`);
41
60
 
42
61
  const server = new McpServer({
43
62
  name: "centrali",