4D MCP Server

Model Context Protocol (MCP) server for 4D REST API integration. Provides tools for authentication, data querying, manipulation, and ORDA class function calls.

Features

• Authentication: Login with username/password or hashed password

• Schema Inspection: Get database catalog information

• Data Querying: Query dataclasses with filtering, sorting, and pagination

• Data Manipulation: Create, update, and delete records

• ORDA Functions: Call class functions on the 4D server

• Session Management: Automatic session cookie handling

Related MCP server: ERPNext MCP Server

Installation

For MCP Client Usage

Install globally via npm:

npm install -g 4d-mcp

For Development

1. Clone and install dependencies:

git clone <repository-url>
cd 4d-mcp
npm install

2. Configure environment variables:

cp .env.example .env

Edit .env with your 4D server settings:

FOURD_BASE=https://your-4d-server:port
FOURD_USER=username
FOURD_PASSWORD=password
FOURD_SESSION_MINUTES=60
FOURD_ALLOW_SELF_SIGNED=true  # For development only

3. Build the project:

npm run build

Usage

Development

npm run dev

Production

npm run build
npm start

Available Tools

1. login

Authenticate with the 4D server and establish a session.

Parameters:

• user (optional): Username override

• password (optional): Password override

• hashed (optional): Whether password is hashed

• minutes (optional): Session duration override

2. catalog

Get database schema information.

Parameters:

• all (optional): Include all catalog details

3. query

Query data from a dataclass.

Parameters:

• dataClass (required): Dataclass name

• filter (optional): 4D query filter

• orderby (optional): Sort specification

• top (optional): Max records to return

• skip (optional): Records to skip (pagination)

• attributes (optional): Specific attributes to include

• expand (optional): Related attributes to expand

4. upsert

Create or update records.

Parameters:

• dataClass (required): Dataclass name

• body (required): Record data (object or array)

5. delete

Delete records from a dataclass.

Parameters:

• dataClass (required): Dataclass name

• key (optional): Specific record key

• filter (optional): Query filter for bulk delete

6. callFunction

Call ORDA class functions.

Parameters:

• target (required): Interface/dataclass name

• func (required): Function name

• params (optional): Function parameters array

4D Server Requirements

1. Enable REST Server: Set "Expose REST server" in 4D settings

2. Configure Exposure: Ensure dataclasses and attributes are exposed

3. HTTPS: Use HTTPS in production

4. Authentication: Configure user authentication as needed

Error Handling

The server provides detailed error messages for:

• Authentication failures (401 errors)

• Missing session cookies

• Invalid parameters

• 4D server errors

Authentication errors will prompt you to run login again.

Security Notes

• Use HTTPS when sending credentials

• Prefer hashed passwords over plain text

• Limit exposed dataclasses and attributes in production

• Never log passwords or session cookies

Testing with MCP Inspector

Use the MCP Inspector to test the server:

npm install -g @modelcontextprotocol/inspector
mcp-inspector

Point the inspector to your built server: node dist/index.js

Client Configuration

Claude Code

Add to your Claude Code configuration file (~/.claude-code/config.json):

{
  "mcpServers": {
    "4d": {
      "command": "npx",
      "args": ["4d-mcp"],
      "env": {
        "FOURD_BASE": "https://your-4d-server.com:443",
        "FOURD_USER": "your-username",
        "FOURD_PASSWORD": "your-password",
        "FOURD_SESSION_MINUTES": "60",
        "FOURD_ALLOW_SELF_SIGNED": "false"
      }
    }
  }
}

Cursor

Add to your Cursor settings (Settings > Extensions > MCP > Edit in settings.json):

{
  "mcp": {
    "servers": {
      "4d": {
        "command": "npx",
        "args": ["4d-mcp"],
        "env": {
          "FOURD_BASE": "https://your-4d-server.com:443",
          "FOURD_USER": "your-username",
          "FOURD_PASSWORD": "your-password",
          "FOURD_SESSION_MINUTES": "60",
          "FOURD_ALLOW_SELF_SIGNED": "false"
        }
      }
    }
  }
}

Cline (VS Code Extension)

Add to your Cline MCP settings:

{
  "mcpServers": {
    "4d": {
      "command": "npx",
      "args": ["4d-mcp"],
      "env": {
        "FOURD_BASE": "https://your-4d-server.com:443",
        "FOURD_USER": "your-username",
        "FOURD_PASSWORD": "your-password",
        "FOURD_SESSION_MINUTES": "60",
        "FOURD_ALLOW_SELF_SIGNED": "false"
      }
    }
  }
}

Configuration Notes

• Replace placeholder values with your actual 4D server details

• Use HTTPS in production environments

• Set FOURD_ALLOW_SELF_SIGNED to "true" only for development with self-signed certificates

• Example configuration files are available in the examples/ directory