Nexus MCP Client

HTTP client for connecting to Nexus MCP Multi-Tenant Server with automatic credential header injection.

Features

• 🔐 Automatic Credential Headers: Transparently injects credentials from environment variables
• 🌐 HTTP Transport: Reliable HTTP POST communication with MCP servers
• 🧪 Built-in Diagnostics: Comprehensive credential and connection testing
• 📋 Tool Discovery: List and test available MCP tools
• 🔄 Claude Desktop Integration: Seamless proxy mode for Claude Desktop
• 🛡️ Security: Automatic credential masking in logs

Quick Start

Installation

npm install -g as-nexus-mcp-client

Claude Desktop Configuration

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "npx",
      "args": [
        "as-nexus-mcp-client",
        "--url", "http://localhost:3000/mcp/your-client-id"
      ],
      "env": {
        "AZURE_DEVOPS_PAT": "your-52-character-token",
        "AZURE_DEVOPS_ORGANIZATION_URL": "https://dev.azure.com/your-org",
        "AZURE_DEVOPS_PROJECT_ID": "optional-project-id",
        "JIRA_DOMAIN": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-token"
      }
    }
  }
}

Automatic Credential Headers

The client automatically reads environment variables and converts them to HTTP headers:

Azure DevOps

• AZURE_DEVOPS_PAT → X-Azure-DevOps-PAT
• AZURE_DEVOPS_ORGANIZATION_URL → X-Azure-DevOps-Org-URL
• AZURE_DEVOPS_PROJECT_ID → X-Azure-DevOps-Project-ID

Jira

• JIRA_DOMAIN → X-Jira-Domain
• JIRA_EMAIL → X-Jira-Email
• JIRA_API_TOKEN → X-Jira-API-Token

CLI Usage

Basic Connection Test

as-nexus-mcp-client --url http://localhost:3000/mcp/client-id --test

List Available Tools

as-nexus-mcp-client --url http://localhost:3000/mcp/client-id --list-tools

Run Diagnostics

as-nexus-mcp-client --diagnose

Verbose Mode

as-nexus-mcp-client --url http://localhost:3000/mcp/client-id --test --verbose

Diagnostics

The built-in diagnostic tool provides comprehensive information:

as-nexus-mcp-client --diagnose

Sample Output:

🔍 Nexus MCP Client - Credential Diagnostics
==================================================

📍 Environment Info:
   Node Version: v20.0.0
   Platform: darwin
   Client Version: 1.1.0

🔐 Credential Configuration:
   Total headers: 5
   Total size: 234 bytes

   Azure DevOps:
   ✅ Configured
      Headers: 3
      X-Azure-DevOps-PAT: 6yi2***JQQj
      X-Azure-DevOps-Org-URL: https://dev.azure.com/as-digital-solutions
      X-Azure-DevOps-Project-ID: ghost-protocol

   Jira:
   ✅ Configured
      Headers: 3
      X-Jira-Domain: company.atlassian.net
      X-Jira-Email: [email protected]
      X-Jira-API-Token: ATAT***1EB

🧪 Connection Test:
   ✅ Connection successful
   📋 Available tools: 26

💡 Recommendations:
   • All services properly configured
   • Ready for production use

✅ Diagnostics complete

Configuration Examples

Azure DevOps Only

{
  "env": {
    "AZURE_DEVOPS_PAT": "your-token",
    "AZURE_DEVOPS_ORGANIZATION_URL": "https://dev.azure.com/your-org"
  }
}

Jira Only

{
  "env": {
    "JIRA_DOMAIN": "company.atlassian.net",
    "JIRA_EMAIL": "[email protected]",
    "JIRA_API_TOKEN": "your-token"
  }
}

Both Services

{
  "env": {
    "AZURE_DEVOPS_PAT": "azure-token",
    "AZURE_DEVOPS_ORGANIZATION_URL": "https://dev.azure.com/org",
    "JIRA_DOMAIN": "company.atlassian.net",
    "JIRA_EMAIL": "[email protected]",
    "JIRA_API_TOKEN": "jira-token"
  }
}

Security Features

Automatic Credential Masking

• Tokens are automatically masked in logs
• Only first and last 4 characters shown
• URLs and emails remain visible for debugging

Header Size Validation

• Automatic validation of header size limits
• Warning at 16KB, error at 32KB per header
• Total size limit of 64KB for all headers

Session Management

• Unique session IDs for each connection
• Proper connection lifecycle management
• Graceful shutdown handling

Troubleshooting

Connection Issues

401 Authentication Failed

# Check credential configuration
as-nexus-mcp-client --diagnose

# Verify tokens are valid and not expired

403 Access Forbidden

# Verify token permissions
# Azure DevOps: Ensure PAT has 'Work items (full)' scope
# Jira: Ensure API token has proper project access

404 Not Found

# Check server URL and client ID
# Ensure Nexus MCP Server is running
curl http://localhost:3000/health

Credential Issues

No Credentials Configured

# Verify environment variables are set
env | grep -E "(AZURE_DEVOPS|JIRA)"

# Check Claude Desktop config file
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Headers Too Large

# Use credential profiles for large configurations
# Consider server-side credential mapping

Network Issues

Connection Timeout

# Check server status
curl -I http://localhost:3000/health

# Verify firewall settings
# Check network connectivity

API Reference

NexusMCPClient

import { NexusMCPClient } from 'as-nexus-mcp-client';

const client = new NexusMCPClient({
  url: 'http://localhost:3000/mcp/client-id',
  verbose: true
});

await client.connect();
await client.listTools();
await client.disconnect();

CredentialHeadersBuilder

import { CredentialHeadersBuilder } from 'as-nexus-mcp-client';

// Get credential status
const status = CredentialHeadersBuilder.getCredentialStatus();

// Check if any credentials configured
const hasCredentials = CredentialHeadersBuilder.hasAnyCredentials();

// Get configured services
const services = CredentialHeadersBuilder.getConfiguredServices();

Development

Building

npm run build

Testing

npm run dev -- --url http://localhost:3000/mcp/test --test

Publishing

npm version patch
npm publish

Environment Variables Reference

| Variable | Required | Description | |----------|----------|-------------| | AZURE_DEVOPS_PAT | For Azure DevOps | Personal Access Token (52 chars) | | AZURE_DEVOPS_ORGANIZATION_URL | For Azure DevOps | Organization URL (https://dev.azure.com/org) | | AZURE_DEVOPS_PROJECT_ID | Optional | Default project ID | | JIRA_DOMAIN | For Jira | Jira domain (company.atlassian.net) | | JIRA_EMAIL | For Jira | Account email address | | JIRA_API_TOKEN | For Jira | API token from Jira account settings |

License

MIT License - see LICENSE file for details.

Support

• 📚 Documentation: Check this README and diagnostics output
• 🐛 Issues: Use GitHub issues for bug reports
• 💡 Features: Submit feature requests via GitHub
• 🔍 Diagnostics: Use --diagnose flag for troubleshooting