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/