@memberjunction/ai-mcp-client

MemberJunction MCP (Model Context Protocol) Client implementation for consuming tools from external MCP servers. Provides a singleton connection manager with support for multiple transport types, OAuth 2.1 authentication, rate limiting, execution logging, agent integration, and database-backed tool synchronization.

Architecture

graph TD
    subgraph "@memberjunction/ai-mcp-client"
        MCM["MCPClientManager<br/>Singleton Connection Manager"]
        style MCM fill:#2d8659,stroke:#1a5c3a,color:#fff

        ATA["AgentToolAdapter<br/>LLM Tool Format Converter"]
        style ATA fill:#7c5295,stroke:#563a6b,color:#fff

        RL["RateLimiter<br/>Per-Minute & Per-Hour Limits"]
        style RL fill:#b8762f,stroke:#8a5722,color:#fff

        EL["ExecutionLogger<br/>Database Audit Trail"]
        style EL fill:#b8762f,stroke:#8a5722,color:#fff

        subgraph "OAuth 2.1 Module"
            OM["OAuthManager"]
            style OM fill:#7c5295,stroke:#563a6b,color:#fff
            ASD["AuthServerDiscovery"]
            style ASD fill:#7c5295,stroke:#563a6b,color:#fff
            CR["ClientRegistration"]
            style CR fill:#7c5295,stroke:#563a6b,color:#fff
            TM["TokenManager"]
            style TM fill:#7c5295,stroke:#563a6b,color:#fff
            PK["PKCEGenerator"]
            style PK fill:#7c5295,stroke:#563a6b,color:#fff
        end
    end

    subgraph "Transport Types"
        T1["StreamableHTTP"]
        style T1 fill:#2d6a9f,stroke:#1a4971,color:#fff
        T2["SSE"]
        style T2 fill:#2d6a9f,stroke:#1a4971,color:#fff
        T3["Stdio"]
        style T3 fill:#2d6a9f,stroke:#1a4971,color:#fff
        T4["WebSocket"]
        style T4 fill:#2d6a9f,stroke:#1a4971,color:#fff
    end

    MCM --> T1
    MCM --> T2
    MCM --> T3
    MCM --> T4
    MCM --> ATA
    MCM --> RL
    MCM --> EL
    MCM --> OM

    subgraph "External MCP Servers"
        S1["MCP Server A"]
        style S1 fill:#b8762f,stroke:#8a5722,color:#fff
        S2["MCP Server B"]
        style S2 fill:#b8762f,stroke:#8a5722,color:#fff
    end

    T1 --> S1
    T2 --> S2

Installation

npm install @memberjunction/ai-mcp-client

Key Exports

MCPClientManager (Singleton)

Central manager for all MCP server connections. Handles connection lifecycle, tool discovery, tool execution, and database synchronization.

import { MCPClientManager } from '@memberjunction/ai-mcp-client';

const manager = MCPClientManager.Instance;

// Initialize (once at startup)
await manager.initialize(contextUser);

// Connect to an MCP server
await manager.connect('connection-id', { contextUser });

// List available tools
const tools = await manager.listTools('connection-id', { contextUser });

// Call a tool
const result = await manager.callTool('connection-id', 'tool-name', {
    arguments: { param1: 'value1' }
}, { contextUser });

// Sync tools to database (creates Action entities)
await manager.syncTools('connection-id', { contextUser });

// Disconnect
await manager.disconnect('connection-id', { contextUser });

AgentToolAdapter

Converts MCP tools into LLM-compatible tool definitions (OpenAI function calling format, Anthropic tool use format):

import { AgentToolAdapter, createAgentToolAdapter } from '@memberjunction/ai-mcp-client';

const adapter = createAgentToolAdapter(manager);

// Get tools in OpenAI format
const openaiTools = await adapter.getToolsForAgent('connection-id', {
    format: 'openai',
    contextUser
});

// Get tools in Anthropic format
const anthropicTools = await adapter.getToolsForAgent('connection-id', {
    format: 'anthropic',
    contextUser
});

// Execute a tool call from an LLM response
const result = await adapter.executeToolCall('connection-id', {
    name: 'tool-name',
    arguments: { param1: 'value1' }
}, { contextUser });

RateLimiter

Per-connection rate limiting with request queuing:

import { RateLimiter, RateLimiterRegistry } from '@memberjunction/ai-mcp-client';

// Rate limiters are automatically managed per connection
// Configure via MCPServerConnection entity fields:
// - RateLimitPerMinute
// - RateLimitPerHour

ExecutionLogger

Database-backed execution logging for debugging and audit:

import { ExecutionLogger } from '@memberjunction/ai-mcp-client';

const logger = new ExecutionLogger(loggingConfig);

// Get execution statistics
const stats: MCPExecutionStats = logger.GetStats();
const summary: MCPExecutionLogSummary = logger.GetSummary();

OAuth 2.1 Module

Complete OAuth 2.1 implementation for authenticating with MCP servers:

| Class | Purpose | |---|---| | OAuthManager | Top-level OAuth flow orchestration | | AuthServerDiscovery | RFC 8414 authorization server metadata discovery | | ClientRegistration | RFC 7591 dynamic client registration | | TokenManager | Token lifecycle (acquire, refresh, revoke) | | PKCEGenerator | PKCE challenge/verifier generation | | OAuthAuditLogger | Security audit logging |

import { OAuthManager, OAuthAuthorizationRequiredError } from '@memberjunction/ai-mcp-client';

try {
    await manager.connect('oauth-connection-id', { contextUser });
} catch (error) {
    if (error instanceof OAuthAuthorizationRequiredError) {
        // Redirect user to authorization URL
        const authUrl = error.authorizationUrl;
        // After user authorizes, complete the flow
        await OAuthManager.Instance.completeAuthorization(code, state);
    }
}

Type Definitions

The package exports comprehensive type definitions for all aspects of MCP client operations:

| Category | Key Types | |---|---| | Transport/Auth | MCPTransportType, MCPAuthType, MCPServerStatus, MCPConnectionStatus | | Configuration | MCPServerConfig, MCPConnectionConfig, MCPToolDefinition, MCPToolAnnotations | | Operations | MCPCallToolOptions, MCPClientOptions, MCPConnectOptions | | Results | MCPToolCallResult, MCPListToolsResult, MCPSyncToolsResult, MCPTestConnectionResult | | Rate Limiting | RateLimitConfig, RateLimitState, QueuedRequest | | Events | MCPClientEventType, MCPClientEvent, MCPClientEventListener |

Event System

Subscribe to connection and tool execution events:

manager.addEventListener('tool-executed', (event) => {
    console.log(`Tool ${event.toolName} executed in ${event.durationMs}ms`);
});

manager.addEventListener('connection-status-changed', (event) => {
    console.log(`Connection ${event.connectionId}: ${event.status}`);
});

Database Integration

The MCP Client integrates with MemberJunction entities:

• MCP Servers -- Registered MCP server definitions
• MCP Server Connections -- Per-user/per-company connection configurations
• MCP Server Tools -- Discovered tools synced from MCP servers
• Actions -- Auto-generated MJ Action entities from MCP tools (via syncTools)
• Action Params -- Tool parameters mapped to Action parameters

Dependencies

• @modelcontextprotocol/sdk -- Official MCP SDK (client transports, types)
• @memberjunction/core -- MJ framework core
• @memberjunction/core-entities -- Generated entity classes
• @memberjunction/credentials -- Credential resolution for authentication
• @memberjunction/global -- Class factory
• zod -- Schema validation