Command Cloud MCP Server (Node.js)

MCP server providing read-only access to Command Cloud v4 APIs — Setup, Dispatch, Billing, Supply, and Telematics services. Built with the official @modelcontextprotocol/sdk TypeScript SDK.

71 tools total: 68 API tools + 3 monitoring/cost-control tools.

---

Setup (5 minutes)

Prerequisites

• Node.js 18+ — download (v22 LTS recommended)
• Cursor IDE — download
• Command Cloud API credentials — you'll need all five values below

Option A: Automated Install

git clone https://github.com/bripple89/commandcloud_mcp_node.git
cd commandcloud_mcp_node
./install.sh

The script will:

1. Check your Node.js version
2. Install dependencies and build
3. Print a ready-to-paste mcp.json config block with your local paths filled in

Option B: Manual Install

git clone https://github.com/bripple89/commandcloud_mcp_node.git
cd commandcloud_mcp_node
npm install
npm run build

Then add to ~/.cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "command-cloud": {
      "type": "stdio",
      "command": "node",
      "args": ["/full/path/to/commandcloud_mcp_node/dist/server.js"],
      "env": {
        "COMMAND_CLOUD_ENTITY_REF": "<YOUR_ENTITY_GUID>",
        "COMMAND_CLOUD_API_KEY": "<YOUR_X_API_KEY>",
        "COMMAND_CLOUD_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "COMMAND_CLOUD_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "COMMAND_CLOUD_API_SCOPE_REF": "<YOUR_API_SCOPE_REF>"
      }
    }
  }
}

Important: The args path must be the absolute path to dist/server.js on your machine.

Getting Your Credentials

Variable	Where to Find It
COMMAND_CLOUD_ENTITY_REF	Your entity GUID — ask your Command Cloud admin
COMMAND_CLOUD_API_KEY	The x-api-key for the API gateway — ask your admin
COMMAND_CLOUD_CLIENT_ID	OAuth client ID — generated in Command Cloud admin portal
COMMAND_CLOUD_CLIENT_SECRET	OAuth client secret — generated with the client ID
COMMAND_CLOUD_API_SCOPE_REF	API scope ref — defines which services you can access

Verify It Works

1. Restart Cursor completely (Cmd+Q on macOS, then reopen)
2. Open Cursor Settings → MCP — you should see "command-cloud" with a green dot
3. In a chat, ask: "Check the Command Cloud auth status"

You should see a response showing authenticated: true and your token expiry times.

---

Authentication

The server handles a two-step OAuth flow automatically:

1. Step 1 (Login): Your client credentials → refresh token (~24h lifetime)
2. Step 2 (Refresh): Refresh token → access token (~1h lifetime)

When tokens expire, the server refreshes or re-authenticates automatically. You never need to manually manage tokens.

Startup Modes

Mode	Required Env Vars	When to Use
Client Credentials (recommended)	CLIENT_ID, CLIENT_SECRET, API_SCOPE_REF	Fully automatic — handles all token lifecycle
Direct Token	COMMAND_CLOUD_REFRESH_TOKEN	Quick testing with a pre-issued token
Both	All of the above	Maximum resilience — falls back to credentials on token expiry

---

What Can I Ask?

Once connected, you can ask natural language questions in Cursor. The AI will call the right tools automatically:

Question	Tools Used
"List all active customers with their payment terms"	list_customers
"Give me a customer profile for Acme Construction"	get_customer, get_customer_scorecard, list_orders
"Who are my top 5 customers by revenue?"	list_customers, list_orders, list_tickets
"Show today's dispatch orders"	list_orders
"What's the inventory at the Springtown plant?"	list_locations, list_inventory_balances
"Check the auth status"	cloud_auth_status
"How much have we used this session?"	cloud_usage

---

Tools (71 total)

Setup (37 tools)

list_customers, get_customer, list_products, get_product, list_locations, get_location, list_mixes, get_mix, list_drivers, list_vehicles, list_price_books, list_price_adjustments, list_payment_terms, list_payment_methods, list_contacts, list_projects, list_carriers, list_entities, list_users, list_product_types, list_product_strengths, list_product_slumps, list_concrete_classes, list_product_groups, list_cancel_reasons, list_shipping_methods, list_unloading_methods, list_work_types, list_market_segments, list_sales_channels, list_credit_codes, list_accounting_periods, list_vendors, list_trailers, list_load_stations, list_prospects

Dispatch (17 tools)

list_orders, get_order, list_tickets, get_ticket, list_jobs, get_job, list_alerts, dismiss_alert, list_batch_results, list_order_requests, list_order_history, list_loads, list_quotes, list_test_results, get_customer_scorecard

Billing (7 tools)

list_billables, get_billable, list_invoices, get_invoice, list_tax_codes, get_billing_settings, list_billing_lrr

Supply (6 tools)

list_inventory_balances, list_inventory_balance_history, list_inventory_transactions, list_inventory_transaction_history, list_inventory_demand, list_ticket_inventory_status

Telematics (4 tools)

list_alert_events, list_driver_events, list_location_events, list_status_events

Monitoring (3 tools)

cloud_auth_status, cloud_usage, cloud_set_max_response

---

Cost Controls

Large API responses can consume LLM tokens. The server has built-in safeguards:

Control	What It Does
Auto-truncation	Responses over 200K chars (~50K tokens) are automatically trimmed. You'll see a _truncated field showing how many records were cut.
cloud_usage	Ask "show my usage" — see total API calls, response sizes, and estimated token cost for the session.
cloud_set_max_response	Lower the limit (e.g., 50K chars) for budget-conscious sessions.
pickFields	Most list tools accept field names to reduce payload 80–90%. Ask for "just names and codes" to keep responses lean.

---

Security

This server has been reviewed for CISO approval. See SECURITY.md for the full assessment.

Key points:

• Read-only — cannot create, modify, or delete any data
• No network listener — runs as a local subprocess, no ports exposed
• No data caching — API responses pass through memory, nothing written to disk
• Auto-rotating tokens — access tokens expire in 1 hour, refresh tokens in 24 hours
• 2 runtime dependencies — @modelcontextprotocol/sdk (Anthropic) and zod

---

Troubleshooting

Server Not Showing in Cursor

1. Verify the path in mcp.json → args is correct and absolute
2. Restart Cursor completely (Cmd+Q, not just close window)
3. Check Cursor Settings → MCP for error messages

Authentication Errors

1. Verify all 5 env vars are set correctly in mcp.json
2. Ask "check auth status" — look at can_login and authenticated fields
3. If authenticated: false, verify your credentials with your Command Cloud admin

Checking Logs

The server logs to stderr, visible in Cursor's MCP output:

• macOS: ~/Library/Application Support/Cursor/logs/ → search for command-cloud
• Look for [auth] and [api] prefixed lines

Updating

cd commandcloud_mcp_node
git pull
npm ci
npm run build
# Restart Cursor

---

Development

# Dev mode (no build step, auto-recompiles)
npm run dev

# Production build
npm run build
npm start

The server is written in TypeScript with strict mode enabled. Source is in src/, compiled output in dist/.