Files

2026-03-13 15:00:22 +00:00

4.7 KiB

Raw Blame History

Sage X3 GraphQL MCP Server

MCP server that enables AI agents to query Sage X3 ERP data via GraphQL. Read-only access to structure, master data, products, purchasing, and stock entities.

Quick Start

# Install dependencies
bun install

# Run the server (sandbox mode — no credentials needed)
bun run src/index.ts

The server starts in sandbox mode by default, connecting to the public Sage X3 demo API.

Configuration

All configuration is via environment variables:

Variable	Required	Default	Description
`SAGE_X3_URL`	No	Demo URL	Sage X3 GraphQL API URL
`SAGE_X3_ENDPOINT`	Authenticated only	—	X3 endpoint name
`SAGE_X3_CLIENT_ID`	Authenticated only	—	Connected app client ID
`SAGE_X3_SECRET`	Authenticated only	—	Connected app secret
`SAGE_X3_USER`	Authenticated only	—	X3 user
`SAGE_X3_TOKEN_LIFETIME`	No	`600`	JWT lifetime in seconds
`SAGE_X3_TLS_REJECT_UNAUTHORIZED`	No	`true`	TLS certificate validation
`SAGE_X3_MODE`	No	Auto-detect	`sandbox` or `authenticated`

Mode is auto-detected: if SAGE_X3_CLIENT_ID, SAGE_X3_SECRET, and SAGE_X3_USER are all set, the server uses authenticated mode. Otherwise it falls back to sandbox.

Available Tools

`introspect_schema`

Discover available Sage X3 GraphQL types and their fields.

{ "typeName": "xtremX3Products" }

Without arguments, lists all X3 domain types (xtrem*). With a typeName, returns detailed field information.

`query_entities`

Query/search Sage X3 entities with filtering, sorting, and pagination.

{
  "rootType": "xtremX3MasterData",
  "entity": "businessPartner",
  "fields": ["code", "description1", "country.code"],
  "filter": "{country: {code: {_eq: 'FR'}}}",
  "first": 10
}

`read_entity`

Read a single entity by its identifier.

{
  "rootType": "xtremX3MasterData",
  "entity": "businessPartner",
  "id": "AE003",
  "fields": ["code", "description1", "country.code"]
}

`aggregate_entities`

Run aggregation queries (min, max, count, distinctCount) on entities.

{
  "rootType": "xtremX3Products",
  "entity": "product",
  "aggregateFields": [
    { "field": "productWeight", "operations": ["min", "max", "count"] }
  ]
}

`execute_graphql`

Execute a raw GraphQL query. Use for complex queries with aliases, fragments, or variables.

{
  "query": "{ xtremX3Products { product { query(first: 5) { edges { node { code description1 } } } } } }"
}

All tools are read-only — mutations are blocked.

Available Resources

Knowledge base resources for AI agent context:

URI	Description
`sage-x3://knowledge/overview`	Sage X3 API overview, root types, and entity structure
`sage-x3://knowledge/query-patterns`	Common GraphQL query patterns and examples
`sage-x3://knowledge/filter-syntax`	Filter operators and expression syntax
`sage-x3://knowledge/pagination-sorting`	Cursor-based pagination and sorting
`sage-x3://knowledge/error-codes`	Error codes and troubleshooting

Available Prompts

Prompt	Arguments	Description
`search-entities`	`entity`, `criteria`	Search for entities matching criteria
`lookup-entity`	`entity`, `id`	Look up a specific entity by ID
`explore-data`	—	Explore what data is available in the X3 instance
`analyze-data`	`entity`, `question`	Analyze entity data with aggregation

Usage with MCP Clients

OpenCode

Add to opencode.json:

{
  "mcp": {
    "sage-x3-graphql": {
      "type": "local",
      "command": ["bun", "run", "src/index.ts"],
      "enabled": true
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "sage-x3-graphql": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "/path/to/sage-graphql-mcp",
      "env": {
        "SAGE_X3_URL": "https://your-x3-instance.example.com/api",
        "SAGE_X3_CLIENT_ID": "your-client-id",
        "SAGE_X3_SECRET": "your-secret",
        "SAGE_X3_USER": "your-user"
      }
    }
  }
}

Sandbox Mode

The server includes a built-in sandbox mode that connects to the public Sage X3 demo API:

Demo API: https://api-devna.dev-sagex3.com/demo/service/X3CLOUDV2_SEED/api
Explorer UI: https://apidemo.sagex3.com/demo/service/X3CLOUDV2_SEED/explorer/

No credentials required — just start the server and begin querying. Useful for testing, development, and exploring the X3 data model.

Development

# Type checking
bun run typecheck

# Run tests
bun test

# Build
bun run build

# Dev mode (watch)
bun run dev

4.7 KiB Raw Blame History