sage-mcp-server

MCP server providing read-only access to Sage X3 ERP data through both REST and SOAP APIs. Exposes 9 tools that let LLMs query business objects, read records, search data, and inspect entity schemas — all without modifying any X3 data.

Quick Start

npm install
cp .env.example .env   # edit with your X3 credentials
npm run build
npm start

Tools

Tool	Description
sage_health	Check X3 REST and SOAP API connectivity
sage_query	Query records via REST with pagination, filtering, and sorting
sage_read	Read a single record by primary key via REST
sage_search	Search records with flexible text matching across fields
sage_list_entities	Discover available REST entity types on the endpoint
sage_get_context	Get entity field names and sample structure
sage_soap_read	Read a single record via SOAP by key fields
sage_soap_query	Query records via SOAP with list size control
sage_describe_entity	Get field definitions with types, lengths, and labels

All tools are annotated as readOnlyHint: true — they never modify X3 data.

Configuration

Variable	Required	Default	Description
SAGE_X3_URL	Yes	—	Base URL of X3 server (e.g. http://x3-server:8124)
SAGE_X3_USER	Yes	—	Web service user with API access
SAGE_X3_PASSWORD	Yes	—	Password for the web service user
SAGE_X3_ENDPOINT	Yes	—	X3 endpoint folder (e.g. X3V12, SEED)
SAGE_X3_POOL_ALIAS	No	SEED	SOAP connection pool alias
SAGE_X3_LANGUAGE	No	ENG	Language code for SOAP responses
SAGE_X3_REJECT_UNAUTHORIZED	No	true	Set to false for self-signed TLS certificates
MCP_TRANSPORT	No	stdio	Transport mode: stdio or http
MCP_HTTP_PORT	No	3000	Port for HTTP transport mode

Usage Examples

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sage-x3": {
      "command": "node",
      "args": ["/path/to/sage-mcp-server/dist/index.js"],
      "env": {
        "SAGE_X3_URL": "http://your-x3-server:8124",
        "SAGE_X3_USER": "your_user",
        "SAGE_X3_PASSWORD": "your_password",
        "SAGE_X3_ENDPOINT": "X3V12"
      }
    }
  }
}

Opencode

Add to opencode.json:

{
  "mcp": {
    "sage-x3": {
      "type": "local",
      "command": ["node", "/path/to/sage-mcp-server/dist/index.js"],
      "env": {
        "SAGE_X3_URL": "http://your-x3-server:8124",
        "SAGE_X3_USER": "your_user",
        "SAGE_X3_PASSWORD": "your_password",
        "SAGE_X3_ENDPOINT": "X3V12"
      }
    }
  }
}

HTTP Transport

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npm start

The server listens on POST /mcp for Streamable HTTP MCP connections.

Development

npm run dev          # run with tsx (hot reload)
npm test             # run all tests
npm run test:watch   # watch mode
npm run typecheck    # type check without emitting
npm run build        # compile TypeScript to dist/