Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Upmind MCP Server show me my recent invoices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol server for the Upmind platform: bundled API documentation search plus 97 live admin tools covering the daily operations of a hosting business — tickets, billing, services, clients, orders, provisioning, promotions, security, and reporting.
Built for and verified against a production Upmind organisation.
97 tools across 15 toolsets (read-only / write / destructive all annotated)
Secure auth CLI — session tokens stored in the macOS Keychain, never plaintext; upmind-mcp token set imports a fresh token straight from your clipboard
Read-only mode (UPMIND_READ_ONLY=true) blocks every write tool
Token-efficient responses — list tools return compact summaries (pass full: true for raw records)
Resilient API client — retry with backoff on 429/5xx, timeouts, Upmind field-error extraction, 401 renew-and-replay
Refreshable docs — npm run update-docs pulls the latest reference from apidocs.upmind.com (1,270+ endpoints incl. the web hosting module)
Related MCP server: Upmind MCP Server
claude mcp add --transport stdio --scope user upmind -- npx -y github:spidyhost-crm/upmind-mcp-servernpx fetches and builds the server automatically; your config and tokens live in ~/.upmind-mcp/ + the Keychain, so updates never touch them.
git clone git@github.com:spidyhost-crm/upmind-mcp-server.git && cd upmind-mcp-server
npm install && npm run build
claude mcp add --transport stdio --scope user upmind -- node $(pwd)/dist/index.jsYour admin token controls the whole business — treat it accordingly. Two modes:
Nothing long-lived is ever stored. Session tokens expire after ~1 hour.
Log into your Upmind admin as usual
DevTools → Network → any api.upmind.io request → copy the Bearer token
npx upmind-mcp token set — reads the clipboard, validates against the live API, stores in the macOS Keychain
When it expires, tools return a clear error telling you to repeat step 2–3.
upmind-mcp login (email + password + 2FA) stores a session and refresh token in the Keychain; the server renews access tokens itself and rotates the stored pair. Revoke anytime by logging that session out in Upmind or upmind-mcp token clear.
upmind-mcp token set|show|clear manage the stored token (Keychain-backed)
upmind-mcp login full login with auto-renewal
upmind-mcp whoami verify credentials against the live API
upmind-mcp status show config, backend, token expiryKeychain storage (macOS): tokens encrypted at rest by the OS; UPMIND_TOKEN_BACKEND=file falls back to ~/.upmind-mcp/tokens.json chmod 600
Least privilege: create a dedicated staff/API user in Upmind with a restricted role for this server instead of using an owner account
IP whitelisting: use the built-in list/add/remove_whitelisted_ip tools to restrict org admin access to known IPs — a leaked token becomes useless elsewhere. Add your current IP first!
Read-only mode: UPMIND_READ_ONLY=true hard-blocks all 48 write tools server-side
Destructive-tool annotations: cancels/refunds/deletes carry destructiveHint so MCP clients can require confirmation
Never paste tokens into chats or commit them — .env, .tokens.json are gitignored; the CLI clipboard flow avoids both
Config is layered: real env vars → project .env → ~/.upmind-mcp/config.env.
Env | Effect |
| Your admin URL (e.g. |
| Default |
| Every write tool refuses to run |
| Applied when tools accept |
| Expose only selected toolsets (docs always on) |
|
|
| Env-based auth alternatives to the CLI |
| Client tuning |
docs — search_endpoints, get_endpoint_details, list_api_groups, get_group_endpoints
brands — list_brands, get_brand
catalog — list_categories, create_category, list_products, get_product, create_product, update_product, duplicate_product, copy_product_to_brand, reorder_products, list_pricelists, get_product_prices, sync_pricing, list_currencies, get_upgrade_paths, set_upgrade_paths, remove_upgrade_path
provisioning — list_provision_fields, get_provision_field_values, update_provision_field_values, list_provision_configs, list_provision_functions
contracts (services) — list_contracts, get_contract, count_active_services, cancel_contract, cancel_contract_product, activate_contract_product, set_contract_product_renewal, update_contract_product_dates, update_contract_product_price, change_contract_product (upgrades, with dry_run), trigger_provision
clients — list_clients, get_client, create_client, update_client, list_client_accounts, reset_client_password, resend_client_verification
orders — list_orders, get_order, create_order (quick order → invoice), cancel_order, convert_order_to_invoice
billing — list_invoices, get_invoice, credit_invoice, apply_client_credit, refund_invoice, create_renewal_invoice, refresh_invoice, list_payments, add_payment, refund_payment, list_gateways, get_wallet_balance, list_wallet_transactions, refund_from_wallet
tickets — list_tickets, get_ticket, get_ticket_messages, create_ticket, reply_ticket (incl. private staff notes), update_ticket, assign_ticket, list_ticket_departments
marketing — list_promotions, get_promotion, create_promotion, update_promotion, disable_promotion, list_leads, create_lead, update_lead, convert_lead_to_client
emails — list_email_history, get_email, resend_email
webhooks — list_webhooks, list_webhook_events, create_webhook, update_webhook, delete_webhook
users — list_users, get_user
reports — get_stats, list_reports, run_report
security — list_whitelisted_ips, add_whitelisted_ip, remove_whitelisted_ip
Verified against production:
Admin prefix: staff tokens call https://api.upmind.io/api/admin/...; doc URLs starting admin/ map to the same path with the prefix stripped.
Pagination: Upmind returns 10 results by default — always pass limit/offset; responses carry total. The client's getAll() auto-paginates (capped at 1,000 items).
Filters: filter[field]=value, e.g. filter[status.code], filter[product.id], filter[contract.client_id]. ⚠️ filter[status]=... on invoices causes a 500 database error — always filter status via status.code.
Status codes are prefixed: contract_active, contract_suspended, invoice_unpaid, invoice_paid, ticket_in_progress, ticket_waiting_response (short forms like unpaid also match).
Relations load via with=a,b,c; raw list rows only carry *_id fields (e.g. tickets have status_id but no status object without with=status).
OAuth: POST https://api.upmind.io/oauth/access_token with admin_password / admin_twofa / refresh_token grants; the Origin header of your admin domain is required when no oauth client id is sent. Access tokens live ~1 hour; refresh tokens rotate on every use.
Emails: the API exposes delivery metadata (sent, bounced, error_message) but not rendered bodies.
src/
├── index.ts # stdio server entry (existing MCP registrations)
├── cli.ts # upmind-mcp CLI: token/login/whoami/status + serve
├── serve.ts # shared server bootstrap
├── server.ts # assembles McpServer from the tool registry
├── registry.ts # ToolDef type + shared schema fragments
├── config.ts # layered env/.env/~/.upmind-mcp config
├── api/
│ ├── client.ts # HTTP client: retries, timeouts, error shaping
│ ├── auth.ts # TokenManager: OAuth renewal, expiry handling
│ └── token-store.ts # Keychain (macOS) / file token storage
├── docs/ # documentation cache, search, and doc tools
├── tools/ # one file per domain, exporting ToolDef[]
└── utils/compact.ts # response summarisation helpers
scripts/
├── update-docs.mjs # refresh bundled docs (npm run update-docs)
└── smoke.mjs # read-only live smoke test (npm run smoke)
data/ # bundled apidoc JSON (refreshable)Adding a tool = adding one entry to a domain file. server.ts handles registration, read-only enforcement, annotations, and error shaping centrally.
npm run build # compile
npm run typecheck # type check only
npm run smoke # read-only smoke test against the live API
npm run update-docs # refresh bundled API docsMIT
Activate a pending/inactive contract product (marks the service active).
Inputs: contract_id (required), contract_product_id (required).
Record a payment against an invoice — typically an offline/manual payment through an offline gateway (see list_gateways), or charge a stored payment method. amount must be in the invoice currency. DESTRUCTIVE: records money movement.
Inputs: amount (required), invoice_id (required), extra, gateway_id, +1 more.
Whitelist an IP for the organisation (or one staff user). CAUTION: once a whitelist is active, access from other IPs is blocked — add your current IP first.
Inputs: ip (required), user_id, description.
Pay (part of) an invoice using the client's wallet/credit balance.
Inputs: invoice_number (required), credit_amount.
Assign a ticket to a staff user (see list_users), or unassign with user_id omitted.
Inputs: ticket_id (required), user_id.
Cancel a whole contract or specific products on it. DESTRUCTIVE: this cancels live services. Provide a cancellation_reason; optionally limit to specific contract product UUIDs.
Inputs: contract_id (required), cancellation_reason (required), product_ids.
Cancel a single service on a contract, with refund control. refund_mode: 0 = no refund, 1 = full refund, 2 = pro-rata refund. DESTRUCTIVE: cancels a live service.
Inputs: contract_id (required), contract_product_id (required), refund_mode, refund_source, +1 more.
Cancel a pending order. DESTRUCTIVE.
Inputs: order_id (required).
Upgrade or downgrade a contract product to a different product (with pro-rata invoice/credit note). Set dry_run=true first to preview the billing impact without changing anything.
Inputs: contract_id (required), new_product_id (required), contract_product_id (required), price, +5 more.
Convert a lead into a real client record.
Inputs: lead_id (required).
Convert a draft order/basket into a real invoice.
Inputs: order_id (required).
Copy a product into a different brand (multi-brand catalogue management).
Inputs: brand_id (required), product_id (required), category_id.
Count active contract products for a product.
Inputs: product_id (required).
Create a new product category (or subcategory via parent_id) for a brand.
Inputs: name (required), brand_id (required), parent_id.
Create a new client under a brand. Provide email + name; optionally create login credentials. Use "extra" for additional fields (language_code, currency_code, …).
Inputs: email (required), brand_id (required), extra, lastname, +4 more.
Create a sales lead (prospect) — e.g. from an inbound enquiry.
Inputs: name (required), brand_id (required), email, phone, +3 more.
Create an order for a client via the admin quick-order flow. By default converts straight to an invoice (convert=true). Each product needs product_id and billing_cycle_months; selling_price overrides list pricing. PRODUCTION: creates real billing documents.
Inputs: products (required), client_id (required), extra, notes, +4 more.
Create a new product in a category. Sensible defaults: single product, single-option order type, monthly billing. Use "extra" for any additional Upmind product fields (see docs endpoint PostAdminProducts). PRODUCTION: creates a live product (hidden from clients unless clients_can_order is true).
Inputs: name (required), brand_id (required), category_id (required), extra, +8 more.
Create a promotion code. type: 1 = fixed amount (needs currency_id), 2 = percentage. Applies to all products unless restricted via "extra" (products, pricelists, billing_cycles).
Inputs: code (required), name (required), type (required), amount (required), +10 more.
Generate the next recurring (renewal) invoice for a contract now, instead of waiting for the scheduler. Optionally scope to one contract product.
Inputs: contract_id (required), contract_product_id.
Open a new support ticket on behalf of a client (e.g. to document a phone call or start an outbound conversation).
Inputs: body (required), subject (required), client_id (required), priority, +3 more.
Create a webhook endpoint. Optionally pass subscription event codes to subscribe immediately.
Inputs: url (required), name, secret, enabled, +1 more.
Issue a credit note against an invoice. Omit amount to credit the full remaining amount, or set full_credit=true. refund_source: 0 = original payment source, 1 = wallet. DESTRUCTIVE: moves money / changes billing records.
Inputs: invoice_id (required), amount, full_credit, refund_source, +1 more.
Delete a webhook endpoint. DESTRUCTIVE.
Inputs: webhook_id (required).
Disable a promotion so it can no longer be used.
Inputs: promotion_id (required).
Clone an existing product within the same brand. The copy is created as "{name} Copy".
Inputs: product_id (required).
Get full details for one brand.
Inputs: brand_id (required).
Get client details. Common "with" values: emails, phones, addresses, accounts, tags, custom_fields.
Inputs: client_id (required), with.
Get a contract with its products and related data. Common "with" values: products, client, products.product, products.status.
Inputs: contract_id (required), with.
Get delivery details for one sent email: recipient, subject, sent/bounced state, and error/bounce data. (Upmind does not expose the rendered body via the API.)
Inputs: email_id (required).
Get full details for one API endpoint: parameters, response schema, headers, and permissions. Accepts the endpoint name (e.g. "GetAdminProducts") or an exact URL pattern.
Inputs: name (required).
List every endpoint in one API group/category (e.g. "Contracts", "Admin_Products").
Inputs: group (required), includeDetails.
Get one invoice. Common "with" values: products, payments, client, credit_notes.
Inputs: invoice_id (required), with.
Get one order with its products and totals.
Inputs: order_id (required), with.
Get full product details. Use "with" to include related data: prices, provision_field_values, allowed_migrations, options, products_attributes.
Inputs: product_id (required), with.
Get all prices for one product across all pricelists, currencies, and billing cycles.
Inputs: product_id (required).
Get full details of one promotion (products, restrictions, usage).
Inputs: promotion_id (required).
Get the current provision field values configured on a product.
Inputs: product_id (required).
Quick operational overview: active services, total clients, open tickets, unpaid invoices, and pending orders — optionally scoped to a brand.
Inputs: brand_id.
Get one ticket with its metadata (status, client, assignees). Use get_ticket_messages for the conversation.
Inputs: ticket_id (required), with.
Get the message thread of a ticket with HTML stripped — readable conversation including private staff notes.
Inputs: ticket_id (required), limit, offset.
Get the products a given product is allowed to upgrade/migrate to.
Inputs: product_id (required).
Get details for one staff user.
Inputs: user_id (required).
Get a client's wallet/credit balance. Pass client_id (default account is resolved automatically) or a specific account_id.
Inputs: client_id, account_id.
List all endpoint groups/categories in the Upmind API reference.
Inputs: includeCount.
List all brands in the Upmind organisation with their IDs, domains, and currencies.
Inputs: no named parameters.
List product categories (with subcategories and product counts), optionally scoped to a brand.
Inputs: brand_id.
List the billing accounts of a client (account IDs are needed for wallet operations; most clients have one).
Inputs: client_id (required).
List or search clients by name, email, or company. Filter by brand.
Inputs: limit, offset, search, brand_id.
List contract products (services) with filters: product, client, status code (e.g. "contract_active", "contract_suspended", "contract_cancelled"), brand. Returns a compact summary per service; set full=true for raw records.
Inputs: full, with, limit, offset, +4 more.
List available currencies with their UUIDs, codes, and symbols.
Inputs: no named parameters.
List emails the platform has sent, filterable by client or brand. Useful to confirm whether an invoice reminder, verification, or notification actually went out.
Inputs: limit, offset, brand_id, client_id.
List configured payment gateways (IDs needed for refunds and manual payments).
Inputs: no named parameters.
List invoices with filters: client, status (e.g. "unpaid", "paid", "overdue"), brand. Compact summaries by default; full=true for raw records.
Inputs: full, limit, offset, status, +2 more.
List sales leads/prospects, optionally searching by text.
Inputs: limit, offset, search, brand_id.
List orders/baskets. Use "with" for relations like client, products.
Inputs: with, limit, offset.
List payment transactions, filterable by client or invoice.
Inputs: limit, offset, client_id, invoice_id.
List all pricelists in the organisation.
Inputs: no named parameters.
List products, filterable by brand, category, or exact name.
Inputs: name, limit, offset, brand_id, +1 more.
List promotions/coupon codes.
Inputs: limit, offset.
List provision configurations (e.g. servers) for a provision category code such as "shared-hosting". Omit category_code to list the provision categories themselves.
Inputs: limit, brand_id, category_code.
List the provision blueprint fields (names, types, labels) defined for a product.
Inputs: product_id (required).
List the provision functions available on a contract product (setup, suspend, terminate, getUsage, …). Use the returned function id with trigger_provision.
Inputs: contract_id (required), contract_product_id (required).
List Upmind's built-in reports (revenue, churn, tax, transactions, …) that can be run with run_report.
Inputs: no named parameters.
List ticket departments (IDs needed for creating/moving tickets).
Inputs: no named parameters.
List support tickets with filters (client, status code, department, brand) or full-text search across subjects and message bodies. Status codes: ticket_in_progress, ticket_waiting_response, ticket_resolved, ticket_closed (short forms like "in_progress" also match).
Inputs: full, limit, query, offset, +5 more.
List staff/admin users (IDs are needed for assign_ticket).
Inputs: limit, offset, search.
List a client's wallet transaction history (credits, debits, top-ups).
Inputs: limit, offset, client_id, account_id.
List the event types that webhook endpoints can subscribe to.
Inputs: limit, offset.
List configured webhook endpoints and their subscriptions.
Inputs: no named parameters.
List whitelisted IPs for the organisation, or for one staff user when user_id is given. When a whitelist exists, admin access is only allowed from these addresses.
Inputs: user_id.
Regenerate invoice data and its PDF (e.g. after changing brand details or a template).
Inputs: invoice_id (required).
Manually refund an amount from a client's wallet balance (e.g. paying out unused credit outside the system). DESTRUCTIVE: reduces the client's credit balance.
Inputs: amount (required), client_id (required), currency_code (required), account_id, +2 more.
Record a manual (offline) refund against an invoice or pay out a credit note. Requires the gateway the refund was made through. DESTRUCTIVE: records money movement.
Inputs: gateway_id (required), invoice_id (required), amount.
Refund a captured payment through its gateway, by transaction reference. Omit amount to refund the full overpaid amount. DESTRUCTIVE: moves real money.
Inputs: transaction_id (required), amount.
Remove one upgrade path from a product.
Inputs: product_id (required), migration_product_id (required).
Remove a whitelisted IP entry. DESTRUCTIVE: may lock out whoever uses that address.
Inputs: whitelisted_ip_id (required), user_id.
Reorder products within a category. Pass ALL product UUIDs of the category in the desired display order.
Inputs: product_ids (required).
Post a reply on a ticket. Set is_private=true to add an internal staff note the client cannot see. PRODUCTION: public replies email the client.
Inputs: body (required), ticket_id (required), is_private.
Resend the account verification email to a client.
Inputs: client_id (required).
Resend a previously sent email (e.g. an invoice or verification email that never arrived).
Inputs: email_id (required), dispatch_now.
Trigger a password-reset email for a client (admin-initiated).
Inputs: client_id (required), email.
Run a built-in Upmind report by its code/name with optional parameters (date ranges etc.). Check list_reports first; parameters vary per report.
Inputs: report (required), parameters.
Search the Upmind API reference (1,270+ endpoints) by keyword. Supports multi-word queries; searches names, titles, descriptions, groups, and URLs. Use this to discover the right endpoint before calling live tools or building integrations.
Inputs: query (required), limit.
Turn auto-renewal on or off for a contract product. Turning renewal off schedules the service to expire at the end of the paid period.
Inputs: renew (required), contract_id (required), contract_product_id (required), cancellation_reason.
Set which products a product can be upgraded to. PRODUCTION: changes are live.
Inputs: product_id (required), migration_product_ids (required).
Set/update prices for a product on a specific pricelist. Each entry needs currency_id, billing_cycle_months, and price. PRODUCTION: changes are live immediately.
Inputs: prices (required), product_id (required), pricelist_id (required).
Run a provisioning function (setup, suspend, unsuspend, terminate, getUsage, …) on a contract product. Find function IDs with list_provision_functions. PRODUCTION: executes immediately on the hosting server.
Inputs: contract_id (required), function_id (required), contract_product_id (required), provision_field_values.
Update client profile fields. Use "extra" for any other Upmind client field.
Inputs: client_id (required), extra, notes, lastname, +2 more.
Change suspend/cancel/close scheduling for a contract product: either intervals in days after next_due_date, or explicit hold-off dates (not_suspend_until / not_cancel_until / not_close_until, today or future). Useful to give clients extra time before suspension.
Inputs: contract_id (required), contract_product_id (required), close_interval, cancel_interval, +4 more.
Change the recurring selling price of a contract product (affects future invoices).
Inputs: contract_id (required), selling_price (required), contract_product_id (required), total_price, +1 more.
Update fields on a lead.
Inputs: fields (required), lead_id (required).
Update product fields (name, descriptions, category, visibility flags). Use "extra" for any other Upmind product field. PRODUCTION: changes are live.
Inputs: product_id (required), name, extra, category_id, +5 more.
Update fields of an existing promotion.
Inputs: fields (required), promotion_id (required).
Update provision field values on a product (e.g. {"package_name": "Reseller Tier 2"}). PRODUCTION: affects how new services provision.
Inputs: product_id (required), field_values (required).
Update ticket properties: status (by code, e.g. "closed"), subject, department, priority, or linked service.
Inputs: ticket_id (required), subject, priority, status_code, +2 more.
Update a webhook endpoint (URL, enabled state, name, secret).
Inputs: fields (required), webhook_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 97 tools
Most tools have clear, distinct purposes with detailed descriptions, and each targets a unique resource+action. However, the large number of similar product/contract/update tools (e.g., update_contract_product_dates vs update_contract_product_price) creates some risk of misselection, though descriptions mitigate this.
All tools follow a consistent snake_case verb_noun pattern (list_, get_, create_, update_, delete_, etc.). Minor verb variations like change, sync, and apply do not break the overall predictable naming convention.
With 97 tools, this is an extreme mismatch for an MCP server. The sheer number overwhelms an agent's ability to efficiently select the right tool, far exceeding the recommended 3-15 range and even the 25+ threshold.
The tool set covers comprehensive CRUD and lifecycle operations for clients, products, contracts, orders, invoices, payments, and tickets. Minor gaps exist (e.g., no delete_product, no create_department, no update_invoice), but agents can typically work around these omissions.
Search 16,000+ API operations and 95 built tools by need, then call any of them by name
Find, write, publish and check pages and API references in your DeveloperHub docs from an AI client
Access and search Branch's official API documentation directly within any AI agent or client.
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
