@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