Skip to main content

MCP Server Setup

Three steps: build the server, register it with your assistant, sign in. Budget about five minutes.

Requirements​

  • Node.js 20 or newer, and git.
  • A CloudYali account. The server sees exactly what your own login sees.
  • A client that can launch a local MCP server over stdio. Browser-only assistants cannot.

1. Build the server​

The package is not published to npm yet, so build it from source. A plain npm install @cloudyali/mcp-server will not work today.

git clone https://github.com/cloudyali/cloudyali-mcp-server.git
cd cloudyali-mcp-server
npm install          # installs dependencies and builds dist/ via the prepare script

npm install also runs the build, so there is no separate build step. Note the absolute path to dist/index.js; every client config below needs it.

note

Once the package is on npm, the clone-and-build step disappears and every snippet below can use npx -y @cloudyali/mcp-server in place of node /path/to/.../dist/index.js.

2. Register it with your client​

Claude Code​

One command:

claude mcp add cy -- node /path/to/cloudyali-mcp-server/dist/index.js

On Windows:

claude mcp add cy -- node C:\path\to\cloudyali-mcp-server\dist\index.js

Run /mcp to confirm it shows cy: connected.

The name you register under becomes the tool prefix, so cy gives you mcp__cy__search_actions. A short name keeps tool names readable. The tool descriptions recognise "CloudYali", "cy" and "cloud cost", so the assistant picks them up from natural phrasing either way.

Claude Desktop​

Edit claude_desktop_config.json (Settings → Developer → Edit Config). It lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "cloudyali": {
      "command": "node",
      "args": ["/path/to/cloudyali-mcp-server/dist/index.js"]
    }
  }
}

On Windows, wrap it with cmd /c:

{
  "mcpServers": {
    "cloudyali": {
      "command": "cmd",
      "args": ["/c", "node", "C:\\path\\to\\cloudyali-mcp-server\\dist\\index.js"]
    }
  }
}

Restart Claude Desktop after editing.

Cursor, Windsurf, Cline, Gemini CLI​

These accept the same mcpServers block as Claude Desktop, in their own config file. Restart the client after editing.

VS Code​

.vscode/mcp.json, where the top-level key is servers, not mcpServers:

{
  "servers": {
    "cloudyali": {
      "command": "node",
      "args": ["/path/to/cloudyali-mcp-server/dist/index.js"]
    }
  }
}

OpenAI Codex CLI​

TOML, in ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

[mcp_servers.cloudyali]
command = "node"
args = ["/path/to/cloudyali-mcp-server/dist/index.js"]
Browser-based assistants

ChatGPT on the web and claude.ai in a browser tab cannot spawn a local process, so they cannot use this build. That needs a remote HTTP MCP server, which is not available yet. Desktop and terminal clients work today.

3. Sign in​

On your first data call the assistant will prompt you to authenticate. Run the login tool, or simply ask it to "log in to CloudYali". What happens:

  1. Your browser opens the CloudYali console's authorize page, behind your normal sign-in, including MFA and SSO.
  2. Your terminal prints a short verification code. The browser page shows one too. Authorize only if the two match. This is what stops another local process from opening a login page and harvesting the result.
  3. A refresh token is saved to ~/.cloudyali-mcp/credentials.json (%USERPROFILE%\.cloudyali-mcp\credentials.json on Windows), created with mode 0600 on macOS and Linux and protected by your user profile's ACLs on Windows.

Tokens refresh on their own, so you will not sign in again until the refresh token itself expires. Tokens travel only in the browser URL fragment to a listener on localhost, never to a remote server or any server log.

Headless and CI: set CLOUDYALI_JWT to a Cognito access token to skip the browser flow entirely.

Environment variables​

All optional. The defaults point at CloudYali production. Pass them through the env block of your client config when overriding.

VariableDefaultPurpose
CLOUDYALI_API_URLhttps://api.cloudyali.ioBase URL of the CloudYali API.
PORTAL_URLhttps://console.cloudyali.ioPortal serving the browser login page at /cli-login.
CLOUDYALI_JWTunsetAccess-token override. Bypasses the credentials file and the login flow.
CLOUDYALI_CREDS_DIR~/.cloudyali-mcpWhere credentials are stored.

Check it works​

Ask the assistant something small before anything that matters:

"Using CloudYali, what did we spend last month?"

If it answers with a figure and names the period it used, you are set. If it says it has no credentials, run the login tool.

Troubleshooting​

SymptomWhat it meansWhat to do
"No credentials found"You have not signed in on this machine.Run the login tool.
"Token refresh failed … credentials have been cleared"The refresh token expired or was revoked.Sign in again.
"Token refresh failed … credentials were kept"Transient network or identity-provider error.Retry.
"Portal at … is unreachable"The console, or your PORTAL_URL, is not serving /cli-login.Check the URL. The flow fails fast rather than opening a dead browser tab.
401s after a successful loginCLOUDYALI_API_URL points at a different environment than the one you signed in to.Make the two match.
Client shows the server as failed or disconnectedUsually a wrong path, or npm install did not finish and dist/ is missing.Use an absolute path, then run node <path>/dist/index.js by hand to see the startup error.
Answers look right but the numbers are offThe assistant chose a different grouping, date range or set of cost types than you had in mind.Ask it which filters it applied, then spot-check against the console.

Updating​

The server runs from dist/, so rebuild and reconnect after pulling changes:

git pull
npm install

Then reconnect in your client with /mcp, or restart it.

Next steps​

Last updated on