DealHub Admin MCP Server

Model Context Protocol (MCP) server for DealHub administrators. Manage versions through Claude and other AI agents using natural language.

Features

The DealHub Admin MCP provides 5 tools for version management:

🔍 Query Tools

• list_versions - List all versions with optional status filter (ACTIVE, DRAFT, DEACTIVATED)
• get_version - Get details of a specific version by ID or name
• get_active_version - Get the currently active version

⚡ Action Tools

• activate_version - Activate a version (async operation)
• duplicate_version - Duplicate a version with a new name (async operation)

Prerequisites

• Node.js 18.0.0 or higher
• DealHub admin account with API token

Setup

1. Generate API Token

1. Log in to DealHub as an admin
2. Navigate to Settings → Integrations → Partner API
3. Click Generate Token
4. Copy the clientId and clientSecret

2. Install Dependencies

cd mcp-servers/dealhub-admin
npm install

3. Configure Environment

Create a .env file:

cp .env.example .env

Edit .env and add your credentials:

DEALHUB_API_BASE_URL=https://app.dealhub.io
DEALHUB_API_TOKEN=your-client-id:your-client-secret

Important: Replace your-client-id and your-client-secret with actual values from step 1.

4. Build the Server

npm run build

5. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dealhub-admin": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-servers/dealhub-admin/dist/index.js"],
      "env": {
        "DEALHUB_API_BASE_URL": "https://app.dealhub.io",
        "DEALHUB_API_TOKEN": "your-client-id:your-client-secret"
      }
    }
  }
}

Replace /absolute/path/to/ with the actual path to your project.

6. Restart Claude Desktop

Quit and restart Claude Desktop for changes to take effect.

Usage

Example Natural Language Commands

Once configured, you can use natural language with Claude:

List versions:

• "Show me all versions"
• "List all draft versions"
• "What active versions do we have?"

Get version details:

• "Get details for version ABC123"
• "Show me the version named 'Q1 2026'"

Check active version:

• "Which version is currently active?"
• "What's the active version?"

Activate a version:

• "Activate version ABC123"
• "Make version XYZ the active version"

Duplicate a version:

• "Duplicate version ABC123 as 'Q2 2026'"
• "Copy version ABC123 and name it 'Test Version'"

Tool Details

list_versions

Parameters:

• status (optional): Filter by status - "ACTIVE", "DRAFT", or "DEACTIVATED"

Example:

{
  "status": "DRAFT"
}

Response:

[
  {
    "id": "abc123-def456",
    "name": "Q1 2026",
    "status": "DRAFT",
    "created": "2025-01-15T10:30:00Z"
  }
]

get_version

Parameters:

• versionId (string): Version GUID - OR -
• versionName (string): Version name

Note: Provide either versionId OR versionName, not both.

Example:

{
  "versionId": "abc123-def456"
}

Response:

{
  "guid": "abc123-def456",
  "name": "Q1 2026",
  "status": "DRAFT",
  "createdDate": "2025-01-15T10:30:00Z",
  "comparedToVersionGuid": "xyz789"
}

get_active_version

Parameters: None

Response:

{
  "guid": "xyz789-uvw012",
  "name": "Production 2025",
  "status": "ACTIVE",
  "createdDate": "2024-12-01T08:00:00Z"
}

Or if no active version:

No active version found

activate_version

Parameters:

• versionId (required): Version GUID to activate
• content (optional): Email content for activation notification
• subject (optional): Email subject for activation notification

Example:

{
  "versionId": "abc123-def456",
  "subject": "New version activated",
  "content": "Q1 2026 version is now active"
}

Response:

Version activation started. Request ID: req-789xyz
Status: PENDING

Note: This is an async operation. The version activation happens in the background. Use the request ID to track progress if needed.

duplicate_version

Parameters:

• versionId (required): Source version GUID to duplicate
• newName (required): Name for the duplicated version

Example:

{
  "versionId": "abc123-def456",
  "newName": "Q2 2026"
}

Response:

Version duplication started. Request ID: req-456abc
Status: PENDING

Note: This is an async operation. The version duplication happens in the background. Use the request ID to track progress if needed.

resolve_quote

Advances the stateless quote resolve loop one turn. You submit answers, the server re-evaluates the whole playbook (visibility, defaults, mandatory checks) and returns the next questions plus an opaque state blob. The server keeps nothing between turns — thread state back in on every call.

Parameters:

• opportunityGuid (required): CRM opportunity GUID to bind to
• playbookGuid: required on the first turn (when no state); afterward read from the blob
• state: opaque base64+gzip blob from the previous response — omit on turn 1
• newAnswers: map of attribute path → typed value (e.g. { "Sizing.NumUsers": 50 })
• newProducts, versionGuid, resolveDefaults, runExternalQueries, includeResolvedForm, crmParams, tracePaths: optional

Loop: turn 1 with { opportunityGuid, playbookGuid } → feed state back with newAnswers each turn → stop when ready_to_finalize is true.

⚠️ Host availability. This endpoint only exists on DealHub backends that have the resolve loop deployed (currently dev backends, e.g. http://localhost:9000). Against a host that lacks it — including production hosts like service-us1.dealhub.io — the API returns its HTML 404 page and the tool reports "Endpoint not available on this host." Point DEALHUB_API_BASE_URL at a backend that serves it.

finalize_quote

Finalizes a quote from a resolved state — a terminal resolve pass that persists a Draft quote. Call once resolve_quote reports ready_to_finalize: true, passing the latest state blob. Identity (opportunity / playbook / version) and all answers come from the blob; the only required field is state. Optional overrides: quoteName, docType (PDF / WORD / EXCEL / DealHub), outputDocumentGUID, proposalExpiration (epoch millis).

Returns the created quote — quote_guid, quote_num, quote_name, identifier, and status (Draft). If mandatory answers are still missing, the API returns 422 with missing_mandatory listing the unanswered paths.

Development

Run in Development Mode

npm run dev

Rebuild After Changes

npm run build

Clean Build Artifacts

npm run clean

Architecture

The MCP server uses DealHub's existing OpenAPI endpoints with ByApiToken authentication:

• Authentication: webserver/app/com/valooto/api/auth/ByApiToken.java
• Version API: webserver/app/controllers/openApi/OpenAPIVersionController.java
• API Routes: webserver/conf/api.routes

API Endpoints Used

Tool	HTTP Method	Endpoint	Controller Method
list_versions	GET	/v1/versions	getVersions() (line 590)
get_version	GET	/v1/version/id/:id	getVersionById() (line 669)
get_version	GET	/v1/version/name/:name	getVersionByName() (line 633)
get_active_version	GET	/v1/versions?status=ACTIVE	getVersions() (line 590)
activate_version	POST	/v1/version/activate	activateVersion() (line 766)
duplicate_version	POST	/v1/version/duplicate	duplicateVersion() (line 703)
resolve_quote	POST	/v1/quote/resolve	OpenAPIQuoteResolverController.resolve
finalize_quote	POST	/v1/quote/finalize	OpenAPIHeadlessProposalController

The quote resolve-loop endpoints (/v1/quote/resolve, /v1/quote/finalize) are only available on backends where that loop is deployed.

Troubleshooting

"Authentication failed"

• Verify your token is correct in .env
• Ensure token format is clientId:clientSecret
• Check that your admin user has API access enabled

"No response from DealHub API"

• Verify DEALHUB_API_BASE_URL is correct
• Check your internet connection
• Ensure DealHub is accessible

MCP server not appearing in Claude

• Verify the path in claude_desktop_config.json is absolute (not relative)
• Check that dist/index.js exists (run npm run build)
• Restart Claude Desktop completely
• Check Claude Desktop logs: ~/Library/Logs/Claude/

TypeScript compilation errors

npm run clean
npm install
npm run build

Security

• Never commit .env files - They contain your API credentials
• Token permissions - Tokens have the same permissions as the admin user who generated them
• Rotate tokens - Regularly regenerate API tokens for security

Privacy Policy

Data Collection

The DealHub Admin MCP Server does not collect, store, or transmit any user data except as necessary to communicate with your DealHub instance.

Data Accessed

This MCP server accesses the following data from your DealHub instance:

• Version metadata (names, IDs, statuses, creation dates)
• Active version information
• Version activation and duplication results

Data Storage

• API Credentials: Your DealHub API token (clientId and clientSecret) is stored locally in a .env file on your machine. This file never leaves your computer.
• No Remote Storage: This MCP server does not store any data on remote servers. All operations are performed locally on your machine.
• No Analytics: No usage analytics, telemetry, or tracking data is collected.

Data Transmission

• DealHub API Only: API calls are made exclusively to your configured DealHub instance (DEALHUB_API_BASE_URL).
• HTTPS Encryption: All API communications use HTTPS for encryption in transit.
• No Third Parties: No data is shared with or transmitted to any third-party services.

User Controls

• You have complete control over your API credentials stored in the .env file
• You can revoke API tokens at any time through the DealHub admin interface
• Deleting the .env file removes all stored credentials

Data Retention

• The MCP server retains no data between sessions
• API credentials persist only in your local .env file until you delete them
• No logs or historical data are stored

Data Handling Practices

How Your Data is Used

1. Authentication: Your API token is used to authenticate requests to the DealHub API
2. Version Management: Version data retrieved from DealHub is displayed to you through Claude
3. Temporary Processing: Data is processed in memory during tool execution and discarded immediately after

What We Don't Do

• ❌ Store conversation history
• ❌ Log API requests or responses
• ❌ Share data with third parties
• ❌ Use data for training or analytics
• ❌ Retain data after tool execution completes

API Token Security

• API tokens are stored only in your local .env file
• Tokens are never transmitted except as Bearer tokens in HTTPS requests to DealHub
• The .env file is excluded from version control via .gitignore
• You should use file system permissions to restrict access to .env (e.g., chmod 600 .env)

Compliance

This MCP server:

• Does not handle or store personally identifiable information (PII) beyond what's necessary for API authentication
• Does not access or process health data
• Operates entirely within your local environment and your DealHub instance
• Does not require GDPR, CCPA, or HIPAA compliance as it stores no user data

Security Considerations

Authentication Security

API Token Protection

• Store tokens in .env files, never in code
• Add .env to .gitignore to prevent accidental commits
• Use restrictive file permissions: chmod 600 .env
• Never share tokens in chat, screenshots, or documentation

Token Rotation

• Regularly regenerate API tokens (recommended: every 90 days)
• Immediately revoke tokens if compromised
• Use separate tokens for different environments (dev, staging, prod)

Principle of Least Privilege

• Only admin users should generate API tokens
• Tokens inherit the permissions of the user who generated them
• Do not use super-admin tokens if regular admin access is sufficient

Network Security

• HTTPS Required: The MCP server only communicates with DealHub over HTTPS
• IP Whitelisting: Consider configuring IP restrictions in DealHub's API settings
• Firewall: Ensure your firewall allows outbound HTTPS to your DealHub instance

Local Execution Security

• The MCP server runs locally as a subprocess of Claude Desktop
• No network ports are opened or listening
• Communication with Claude uses stdin/stdout (local IPC only)
• The server cannot be accessed remotely

Dependency Security

• All npm dependencies are from trusted sources (@modelcontextprotocol, axios, dotenv)
• Run npm audit regularly to check for vulnerabilities
• Keep dependencies updated: npm update

Secure Configuration

Claude Desktop Config

• Store API tokens in environment variables in claude_desktop_config.json
• Restrict access to ~/Library/Application Support/Claude/
• On shared machines, ensure other users cannot read your Claude config

Environment Variables

• Never hardcode credentials in package.json or source code
• Use .env files for local development
• Use secure environment variable management for production deployments

Operational Security

• Logging: The MCP server logs minimal information to stderr
• Error Messages: Error messages do not expose sensitive data
• Input Validation: All tool inputs are validated before making API calls

Incident Response

If you suspect a token has been compromised:

1. Immediately revoke the token in DealHub (Settings → Integrations → Partner API)
2. Generate a new token
3. Update your .env file with the new token
4. Restart Claude Desktop
5. Review DealHub API access logs for suspicious activity

Support

For issues or questions:

• DealHub Documentation: https://developers.dealhub.io
• MCP Documentation: https://modelcontextprotocol.io

License

MIT License - See LICENSE file for details.

Copyright (c) 2026 DealHub

This software is provided "as is", without warranty of any kind. See the LICENSE file for full terms.