UteamUP CMMS

@uteamup/mcp-server

MCP server client for UteamUP - enables Claude Desktop/Code integration with automatic OAuth 2.0 authentication

Links

• 📦 [npm Package](https://www.npmjs.com/package/@uteamup/mcp-server) - Install with npx -y @uteamup/mcp-server
• 📖 [Documentation](https://github.com/UteamUP/uteamup-mcp#readme) - Full MCP integration guide
• 🐛 [Issues](https://github.com/UteamUP/uteamup-mcp/issues) - Report bugs and request features
• 💬 [Support](mailto:gisli@uteamup.com) - Get help

What is this?

This package enables AI assistants like Claude Desktop and Claude Code to connect to your UteamUP CMMS system using the Model Context Protocol (MCP). It handles OAuth 2.0 authentication automatically, so you can manage work orders, assets, inventory, and more through natural conversation.

Read-only access for Claude, Grok, Grok Bot, ChatGPT and MiniMax Code

Use the production HTTPS endpoint:

Sign in with your UteamUP account (recommended). A tenant administrator (Tenant.Update) first turns on Allow members to connect AI assistants in the company's API Keys tab. Then each member connects their own assistant; no API key or secret is involved. The consent page offers only companies with an active subscription in which the member is the owner or holds a license; a link ends (401 invalid_token) when that stops being true:

• Grok: open Connectors, choose New Connector → Custom, and enter the endpoint. Grok registers itself (RFC 7591), sends you to the UteamUP consent page, and you pick the company and allow access. Business/Enterprise workspaces require their administrator to provision the connector.
• Grok Bot: add a Custom MCP server, Remote HTTPS with the endpoint on the Bot's Setup → Plugins card; each teammate signs in the first time they use it.
• ChatGPT: add a custom MCP server with the endpoint and choose OAuth; ChatGPT registers itself and you approve on the same consent page.
• Claude: add a custom connector with the endpoint, choose Sign in now and Register automatically, then approve on the UteamUP consent page.
• MiniMax Code: install the uteamup plugin (see Installation) or add the endpoint under Settings → MCP Servers with the Remote / streamable-http transport. MiniMax Code discovers the protected-resource metadata, registers itself (RFC 7591), and opens the UteamUP consent page on first use.

The assistant uses the member's own permissions in the chosen company, and only the read tools below. Access tokens last 60 minutes and refresh tokens rotate on every use. A member disconnects under Profile → Accounts; an administrator sees and revokes every link in the API Keys tab, or with the uteamup_assistant_connection_list / uteamup_assistant_connection_revoke MCP tools. Turning the company setting off stops all links immediately.

Tenant API key (service integrations). The API Keys → Set up UPMate Integration wizard still offers the Private read-only pilot for ChatGPT and Grok: select an active role whose grants are exclusively View/Read and create a separate MCP-enabled key per assistant. In ChatGPT, configure OAuth with predefined client credentials (the API key as Client ID, its secret as Client Secret). Grok only supports sign-in, so use the option above for Grok. Tenant administrators retain the normal key quotas, expiration, IP restrictions, rate limits, rotation, and revocation controls.

Only the existing asset list, asset search, asset-by-GUID, work-order list and work-order search tools are advertised. Current UPMate capability settings, role permissions and tenant scope are checked before discovery and invocation. Guessed write/admin tool calls are denied before execution. The read-only endpoint also rejects a key if its persisted role gains a write or wildcard permission, or if the key is revoked, expired or rotated. These reads do not invoke a UteamUP AI provider or spend UteamUP AI credits.

The Node proxy can use the same endpoint with UTEAMUP_MCP_PATH=/mcp/read-only. Its default /mcp transport retains the existing behavior and role-based authorization. The CLI continues to use existing API-key creation, role selection and revocation commands; no separate credential store or tool implementation is required.

References: OpenAI custom MCP servers and Grok connectors.

Key Features:

• ✅ Automatic OAuth 2.0 + PKCE authentication
• ✅ Token caching with automatic refresh
• ✅ Works with Claude Desktop, Claude Code, and any MCP-compatible client
• ✅ Zero configuration - just provide API credentials
• ✅ Comprehensive error messages
• ✅ Server-Sent Events (SSE) response parsing
• ✅ Proper JSON-RPC 2.0 notification handling
• ✅ NEW: Structured logging with Pino (JSON/text formats)
• ✅ NEW: Configuration validation with Zod
• ✅ NEW: Performance monitoring and metrics
• ✅ NEW: Retry logic with exponential backoff
• ✅ NEW: CLI utilities (--help, --version, --validate-config, --test-auth)
• ✅ Comprehensive test suite

Release status: Beta. The npm badge above shows the published version; see CHANGELOG.md for release details.

Example Conversation:

You: Show me all high-priority work orders in Building A

AI: I found 5 high-priority work orders in Building A...

You: Assign them all to John Doe AI: Done! All 5 work orders are now assigned to John Doe.

---

Installation

No installation needed! Use npx to run directly:

npx -y @uteamup/mcp-server

Or install globally:

npm install -g @uteamup/mcp-server

Install as a Plugin

• Claude Code:

  claude plugin marketplace add UteamUP/uteamup-mcp

claude plugin install uteamup@uteamup

- **Grok Build:**

  grok plugin install https://github.com/UteamUP/uteamup-mcp.git --trust

• Gemini CLI:

  gemini extensions install https://github.com/UteamUP/uteamup-mcp

• MiniMax Code:

  git clone https://github.com/UteamUP/uteamup-mcp.git

cp -R uteamup-mcp/plugins/minimax ~/.minimax/plugins/uteamup

MiniMax Code has no plugin marketplace. It discovers local plugins by folder, rescans automatically, and enables a newly discovered plugin by default. The plugin bundles the read-only MCP server and a cmms skill that teaches the agent when and how to use the tools.

To skip the plugin, add the server directly under Settings → MCP Servers with the Remote / streamable-http transport and this URL (no credentials are stored): https://api.uteamup.com/mcp/read-only

---

Quick Start

1. Get Your API Credentials

1. Log in to UteamUP
2. Go to Tenant Settings → API Keys
3. Click "Set up AI Integration" or "Create API Key"
4. Enable "MCP Enabled" toggle
5. Click Create API Key
6. Copy and save your API Key and Secret (you won't see them again!)

2. Configure Claude Desktop

In Claude Desktop, open Settings → Developer → Edit Config. The configuration file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{

"mcpServers": { "uteamup": { "command": "npx", "args": ["-y", "@uteamup/mcp-server"], "env": { "UTEAMUP_API_KEY": "your-32-character-api-key", "UTEAMUP_SECRET": "your-64-character-secret" } } } }

All UteamUP MCP connections use https://api.uteamup.com. Use a restricted key from a demo workspace when validating an integration.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop. The UteamUP tools will be available automatically.

4. Test the Connection

In Claude, try:

What UteamUP tools do you have access to?

or

Show me all open work orders

That's it! 🎉

---

Configuration

Environment Variables

Required

Optional

API Base URL

The configured base URL must be a bare HTTPS origin. Credentials, paths, query parameters, fragments, and plain HTTP endpoints are rejected.

Always use https://api.uteamup.com, including when running the Node proxy locally. The full MCP endpoint is /mcp; the read-only endpoint is /mcp/read-only.

Permissions

Your AI assistant's permissions are controlled by the role assigned to your API key. To change what the AI can do:

1. Go to Tenant Settings → API Keys in UteamUP
2. Edit your API key
3. Change the Role (e.g., Admin, Supervisor, Read-Only)
4. Changes take effect immediately - no reconnection needed

Tip: Create separate API keys with different roles for different use cases (e.g., one for read-only queries, one for full access).

---

Troubleshooting

Common Issues

"Missing required environment variables"

Cause: UTEAMUP_API_KEY or UTEAMUP_SECRET not set in MCP configuration.

Solution:

1. Check your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows)
2. Verify the env section includes both UTEAMUP_API_KEY and UTEAMUP_SECRET
3. Ensure there are no typos in the environment variable names
4. Restart Claude Desktop after making changes

---

"Authentication failed: Invalid API Key or Secret"

Cause: Wrong credentials or API key has been revoked.

Solution:

1. Verify your credentials in UteamUP:

• Go to Tenant Settings → API Keys
• Check that your API key is Active (not expired or revoked)

1. If credentials are lost, create a new API key:

• Click "Create API Key"
• Enable "MCP Enabled"
• Copy the new credentials

1. Update your MCP configuration with the new credentials
2. Restart Claude Desktop

---

"MCP access denied: Your API key does not have MCP enabled"

Cause: The API key was created without MCP support.

Solution:

1. Create a new API key with MCP enabled:

• Go to Tenant Settings → API Keys
• Click "Set up AI Integration" or "Create API Key"
• Important: Check the "MCP Enabled" toggle
• Click Create API Key

1. Update your MCP con