@mpisaac-syn/coherence-mcp-bundle

Private MCP (Model Context Protocol) bundle server for Coherence Gateway - enables LLMs like Claude to interact with domain-specific OpenAPI tool bundles through a secure, enterprise-ready interface.

Overview

This package provides a bundle-aware MCP server that communicates with the Coherence Gateway, exposing only domain-specific tools based on the configured bundle. This reduces cognitive load on LLMs and improves tool selection accuracy.

Architecture

Claude Desktop
     ↓
MCP Bundle Server (this package)
     ↓
Coherence Gateway (your deployment)
     ↓
Docker Runners (petstore-runner, pulsetrack-runner, etc.)

Installation

This is a private package hosted on GitHub Package Registry. You need authentication to install it.

Step 1: GitHub Authentication

First, create a GitHub Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Create a token with read:packages scope
3. Save the token securely

Step 2: Configure NPM

Option A - Global configuration (recommended):

# Configure npm to use GitHub registry for @mpisaac-syn scope
npm config set @mpisaac-syn:registry https://npm.pkg.github.com

# Login to GitHub registry
npm login --registry=https://npm.pkg.github.com
# Username: your-github-username
# Password: your-personal-access-token
# Email: your-email

Option B - Project-specific .npmrc:

# Create .npmrc in your home directory
echo "@mpisaac-syn:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

Step 3: Install or Use

With npx (no installation required):

npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops

Or install globally:

npm install -g @mpisaac-syn/coherence-mcp-bundle
coherence-mcp --bundle finance-ops

Usage with Claude Desktop

Single Bundle Configuration

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

{
  "mcpServers": {
    "coherence-finance": {
      "command": "npx",
      "args": [
        "@mpisaac-syn/coherence-mcp-bundle",
        "--bundle",
        "finance-ops"
      ],
      "env": {
        "COHERENCE_GATEWAY_URL": "http://localhost:8000",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    }
  }
}

Multiple Bundle Configuration

Configure multiple domain-specific servers:

{
  "mcpServers": {
    "coherence-finance": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "finance-ops"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    },
    "coherence-hr": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "hr-admin"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    },
    "coherence-sales": {
      "command": "npx",
      "args": ["@mpisaac-syn/coherence-mcp-bundle", "--bundle", "sales-mgmt"],
      "env": {
        "COHERENCE_GATEWAY_URL": "https://coherence.synapsedx.co.uk",
        "COHERENCE_JWT_SECRET": "your-jwt-secret"
      }
    }
  }
}

Configuration Options

| Option | Environment Variable | Default | Description | |--------|---------------------|---------|-------------| | --gateway-url | COHERENCE_GATEWAY_URL | http://localhost:8000 | Coherence Gateway URL | | --jwt-secret | COHERENCE_JWT_SECRET | Development default | JWT secret for authentication | | --log-level | COHERENCE_LOG_LEVEL | INFO | Log level (DEBUG, INFO, WARNING, ERROR) | | --bundle | COHERENCE_BUNDLE | None (all tools) | Bundle name for domain-specific filtering |

Bundle Names

Common bundle names configured in Coherence:

• finance-ops - Financial operations tools (invoicing, expenses, budgets)
• hr-admin - HR administration tools (employees, timesheets, benefits)
• sales-mgmt - Sales management tools (CRM, leads, pipeline)
• it-ops - IT operations tools (monitoring, tickets, deployments)
• marketing - Marketing tools (campaigns, analytics, content)

Check with your Coherence administrator for available bundles in your deployment.

Gateway Deployment Flexibility

The MCP bundle server can connect to any Coherence Gateway deployment:

Local Development

npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url http://localhost:8000

Production Cloud

npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url https://coherence.synapsedx.co.uk

Enterprise Internal

npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --gateway-url https://coherence.internal.company.com

Development

To run in development mode:

# Clone the repository
git clone https://github.com/MPIsaac-Syn/coherence.git
cd coherence/mcp_adapter/npm

# Install dependencies
npm install

# Link for local development
npm link

# Test with a bundle
coherence-mcp --bundle finance-ops --log-level DEBUG

Security

• Private Package: Only accessible to authorized GitHub users
• JWT Authentication: Secure communication with Gateway
• No Credentials Storage: API secrets remain in Gateway's Azure Key Vault
• Bundle Isolation: Each MCP server instance only sees its bundle's tools
• Gateway Flexibility: Connect to any authorized Gateway deployment

Troubleshooting

Authentication Issues

# Verify GitHub authentication
npm whoami --registry=https://npm.pkg.github.com

# Re-authenticate if needed
npm logout --registry=https://npm.pkg.github.com
npm login --registry=https://npm.pkg.github.com

Bundle Not Found

# List available bundles (requires gateway connection)
npx @mpisaac-syn/coherence-mcp-bundle --list-bundles

# Check specific bundle
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops --log-level DEBUG

Gateway Connection Issues

# Test gateway health
curl http://localhost:8000/health

# Test with explicit configuration
COHERENCE_GATEWAY_URL=http://localhost:8000 \
COHERENCE_LOG_LEVEL=DEBUG \
npx @mpisaac-syn/coherence-mcp-bundle --bundle finance-ops

Support

• Internal Issues: Contact your Coherence administrator
• Package Issues: https://github.com/MPIsaac-Syn/coherence/issues
• Documentation: https://github.com/MPIsaac-Syn/coherence

License

UNLICENSED - Proprietary to SynapseDx

© 2025 SynapseDx. All rights reserved.