@memberjunction/ai-mcp-server

MemberJunction's Model Context Protocol (MCP) server implementation. Exposes MemberJunction entities, AI agents, actions, and prompts as MCP tools that can be consumed by any MCP-compatible AI client (Claude Desktop, Cursor, custom integrations). Supports both SSE and StreamableHTTP transports, API key and OAuth 2.1 authentication, configurable tool filtering, and dynamic tool generation from entity metadata.

Architecture

graph TD
    subgraph "@memberjunction/ai-mcp-server"
        SRV["MCP Server<br/>Express + MCP SDK"]
        style SRV fill:#2d8659,stroke:#1a5c3a,color:#fff

        CFG["Config System<br/>Entity/Agent/Action/Prompt Tools"]
        style CFG fill:#b8762f,stroke:#8a5722,color:#fff

        CLI["CLI Entry Point<br/>yargs"]
        style CLI fill:#7c5295,stroke:#563a6b,color:#fff

        subgraph "Authentication"
            AK["API Key Auth"]
            style AK fill:#2d6a9f,stroke:#1a4971,color:#fff
            OA["OAuth 2.1 Proxy"]
            style OA fill:#2d6a9f,stroke:#1a4971,color:#fff
            AG["AuthGate"]
            style AG fill:#2d6a9f,stroke:#1a4971,color:#fff
            TV["TokenValidator"]
            style TV fill:#2d6a9f,stroke:#1a4971,color:#fff
            SE["ScopeEvaluator"]
            style SE fill:#2d6a9f,stroke:#1a4971,color:#fff
        end

        subgraph "Tool Types"
            ET["Entity Tools<br/>CRUD + RunView"]
            style ET fill:#7c5295,stroke:#563a6b,color:#fff
            AGT["Agent Tools<br/>Execute Agents"]
            style AGT fill:#7c5295,stroke:#563a6b,color:#fff
            ACT["Action Tools<br/>Execute Actions"]
            style ACT fill:#7c5295,stroke:#563a6b,color:#fff
            PT["Prompt Tools<br/>Execute Prompts"]
            style PT fill:#7c5295,stroke:#563a6b,color:#fff
            MT["Metadata Tool<br/>Entity Schema Info"]
            style MT fill:#7c5295,stroke:#563a6b,color:#fff
        end
    end

    CLI --> SRV
    SRV --> CFG
    SRV --> AG
    AG --> AK
    AG --> OA
    SRV --> ET
    SRV --> AGT
    SRV --> ACT
    SRV --> PT
    SRV --> MT

    MCP_CLIENT["MCP Client<br/>(Claude Desktop, Cursor, etc.)"]
    style MCP_CLIENT fill:#b8762f,stroke:#8a5722,color:#fff

    MCP_CLIENT -->|"SSE / StreamableHTTP"| SRV

Installation

npm install @memberjunction/ai-mcp-server

Quick Start

# Start with all configured tools
npx @memberjunction/ai-mcp-server

# Start with tool filtering
npx @memberjunction/ai-mcp-server --include "Get_*,Run_Agent"

# Start excluding certain tools
npx @memberjunction/ai-mcp-server --include "Get_*" --exclude "Get_AuditLogs_*"

# List available tools without starting
npx @memberjunction/ai-mcp-server --list-tools

# Load filter config from file
npx @memberjunction/ai-mcp-server --tools-file ./my-tools.json

Tool Types

Entity Tools

Dynamically generated from MemberJunction entity metadata. For each configured entity, the server creates:

| Tool Pattern | Description | |---|---| | Get_<Entity>_Record | Retrieve a single record by primary key | | Get_<Entity>_Records | Query records with filtering, sorting, field selection | | Create_<Entity>_Record | Create a new entity record | | Update_<Entity>_Record | Update an existing record | | Delete_<Entity>_Record | Delete a record by primary key | | RunView_<Entity> | Execute a view with ExtraFilter, OrderBy, Fields, MaxRows |

Agent Tools

| Tool | Description | |---|---| | Run_Agent | Execute any configured MemberJunction AI agent with conversation history and template data |

Action Tools

| Tool Pattern | Description | |---|---| | Run_<Action>_Action | Execute a configured MemberJunction action with parameters |

Prompt Tools

| Tool Pattern | Description | |---|---| | Run_<Prompt>_Prompt | Execute a configured AI prompt with template data |

Metadata Tool

| Tool | Description | |---|---| | Get_All_Entity_Metadata | Retrieve all entity metadata including fields, relationships, and field types |

Configuration

Configuration is loaded from mj.config.cjs or environment variables. Key settings:

module.exports = {
    mcpServerSettings: {
        port: 3100,
        entities: [
            { entityName: 'Users', operations: ['get', 'list', 'create', 'update', 'delete', 'runview'] },
            { entityName: 'Companies', operations: ['get', 'list', 'runview'] }
        ],
        agents: [
            { agentId: 'agent-uuid', name: 'Sales Assistant' }
        ],
        actions: [
            { actionId: 'action-uuid', name: 'Send Email' }
        ],
        prompts: [
            { promptId: 'prompt-uuid', name: 'Summarize Content' }
        ]
    }
};

Authentication

API Key Authentication

The server authenticates requests using MemberJunction API keys. The API key is passed via the x-api-key header and maps to a MemberJunction user context.

OAuth 2.1 (Optional)

When configured, the server acts as both an OAuth resource server and an OAuth proxy:

• RFC 9728: Protected Resource Metadata at /.well-known/oauth-protected-resource
• RFC 8414: Authorization Server Metadata discovery
• RFC 7591: Dynamic Client Registration
• PKCE: Required for all authorization code flows
• Scope Evaluation: Tool-level access control via OAuth scopes

The OAuth proxy handles the authorization flow for MCP clients that don't natively support OAuth, proxying between the client and your identity provider.

Tool Filtering

Filter which tools are exposed using glob-style patterns:

{
    "include": ["Get_*", "Run_Agent", "RunView_Users"],
    "exclude": ["*_AuditLogs_*", "Delete_*"]
}

Patterns support:

• * -- Match any characters
• prefix* -- Match tools starting with prefix
• *suffix -- Match tools ending with suffix
• *contains* -- Match tools containing text

CLI Options

| Option | Alias | Description | |---|---|---| | --include | -i | Comma-separated include patterns | | --exclude | -e | Comma-separated exclude patterns | | --tools-file | -f | Path to JSON filter config file | | --list-tools | -l | List tools and exit | | --help | -h | Show help | | --version | -v | Show version |

Dependencies

• @modelcontextprotocol/sdk -- Official MCP SDK (server, transports)
• @memberjunction/ai-agents -- AgentRunner for agent execution
• @memberjunction/ai-prompts -- AIPromptRunner for prompt execution
• @memberjunction/ai-core-plus -- Extended entity classes
• @memberjunction/aiengine -- AIEngine for metadata
• @memberjunction/actions / @memberjunction/actions-base -- Action execution
• @memberjunction/server -- MJ server authentication
• @memberjunction/server-bootstrap-lite -- Class registration manifest
• @memberjunction/sqlserver-dataprovider -- SQL Server data access
• @memberjunction/api-keys -- API key validation
• @memberjunction/credentials -- Credential management
• @memberjunction/config -- Configuration loading
• express -- HTTP server framework
• jsonwebtoken / jwks-rsa -- JWT validation for OAuth
• yargs -- CLI argument parsing
• zod -- Schema validation