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.

72 tools total: 68 API tools + 4 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 (72 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 (4 tools)

cloud_auth_status, cloud_usage, cloud_set_max_response, cloud_health

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

Configuration trust: Use only a trusted mcp.json; do not run startup commands from untrusted sources. Cursor spawns this server as a subprocess using the command and args in mcp.json — malicious config could run arbitrary code with your privileges.

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/.