kore-erpgateway-mcp
Version:
MCP server and client for Kore ERP Universal API - Connect to Kore ERP systems via Model Context Protocol with TypeScript/Node.js CLI and library support
405 lines (299 loc) • 13 kB
Markdown
# Compass AI ERP Gateway MCP Server
[](https://www.npmjs.com/package/kore-erpgateway-mcp)
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org)
> **Enterprise-grade Model Context Protocol server from Compass Agentic Platform**
**ERP Gateway** is Compass AI's enterprise solution for securely connecting AI agents to your ERP systems through the Model Context Protocol (MCP). Built as an ERP-agnostic integration layer, it provides unified access to enterprise resource planning systems, enabling intelligent automation and AI-powered workflows.
## What is ERP Gateway?
ERP Gateway is part of the **Compass AI enterprise offering**, providing:
- **🏢 Enterprise-Ready MCP Server** - Production-grade Model Context Protocol implementation designed specifically for enterprise environments
- **🔒 Secure ERP Connectivity** - Currently supports **SAP Public Cloud** with enterprise-grade security
- **🔄 Unified ERP Layer** - ERP - agnostic architecture that provides consistent access across different ERP systems
- **🚀 Coming Soon** - Sage X3 support in planning
Whether you're using <a href="https://compassap.ai">Compass Agentic Platform</a>, Claude or Cursor, building custom AI agents, or automating enterprise workflows, ERP Gateway provides the secure bridge between AI and your business-critical ERP systems.
## Supported ERP Systems
| ERP System | Status | Description |
|------------|--------|-------------|
| **SAP Public Cloud** | ✅ Available | Public cloud edition |
| **Sage X3** | 🚧 Coming Soon | In active design |
Want to see support for your ERP system? Contact the <a href="https://www.linkedin.com/company/compass-ap">Compass AI team</a>.
## Key Capabilities
- **🤖 MCP Server Mode** - Deploy as a Model Context Protocol server for Claude Desktop and other MCP-compatible applications
- **⚡ CLI Tool** - Command-line interface for testing, debugging, and direct ERP operations
- **📚 TypeScript/Node.js Library** - Embed ERP Gateway capabilities into your custom applications
- **🔐 Enterprise Security** - API key authentication with configurable timeout and retry policies
- **🏗️ ERP-Agnostic Architecture** - Consistent API across different ERP systems (SAP, Sage, and more)
- **🔄 Production-Ready** - Built-in resilience with automatic retry logic and error handling
- **📊 Universal Data Access** - Unified interface for customers, orders, inventory, and other ERP entities
## Table of Contents
- [What is ERP Gateway?](#what-is-erp-gateway)
- [Supported ERP Systems](#supported-erp-systems)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [MCP Server for LLMs](#using-as-mcp-server)
- [CLI Tool](#cli-usage)
- [TypeScript Library](#programmatic-usage)
- [Configuration](#configuration)
- [Examples](#examples)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)
- [Support](#support)
## Prerequisites
- **Compass AI ERP Gateway Server** - Access to your organization's ERP Gateway server endpoint
- **Supported ERP System**:
- SAP public cloud ✅
- Sage ERP (coming soon) 🚧
- **API Key** - Provided by your Compass AI administrator
## Installation
### Global Installation (Recommended for CLI & MCP Server)
```bash
npm install -g kore-erpgateway-mcp
```
### Project Dependency (For Library Usage)
```bash
npm install kore-erpgateway-mcp
```
### Using with npx (No Installation Required)
```bash
npx kore-erpgateway-mcp --help
```
## Quick Start
### Using as MCP Server
Connect Claude Desktop to your SAP public cloud system via ERP Gateway. Add this configuration to your `claude_desktop_config.json`:
**Option 1: Using Installed Package (Recommended)**
```json
{
"mcpServers": {
"kore-erp": {
"command": "kore-erp-mcp-server",
"args": [
"--url", "https://your-erp-server.com",
"--endpoint", "/mcp",
"--api-key", "your-api-key-here",
"--timeout", "30000",
"--retries", "3"
]
}
}
}
```
**Option 2: Using npx (No Installation)**
```json
{
"mcpServers": {
"kore-erp": {
"command": "npx",
"args": [
"kore-erpgateway-mcp",
"--url", "https://your-erp-server.com",
"--api-key", "your-api-key-here"
]
}
}
}
```
**Option 3: Using Environment Variables**
```json
{
"mcpServers": {
"kore-erp": {
"command": "kore-erp-mcp-server",
"env": {
"KORE_ERP_URL": "https://your-erp-server.com",
"KORE_ERP_API_KEY": "your-api-key-here"
}
}
}
}
```
After configuration, restart Claude Desktop. You can now ask Claude to interact with your SAP public cloud system through ERP Gateway!
### CLI Usage
The package includes a powerful CLI for direct interaction with your ERP system:
```bash
# List all available ERP tools
mcp-client --url https://your-erp-server.com --api-key your-key list-tools
# Initialize connection and verify server
mcp-client --url https://your-erp-server.com --api-key your-key init
# Call a specific tool
mcp-client --url https://your-erp-server.com --api-key your-key \
call GetCustomer --args '{"customerId": "12345"}'
# Interactive mode (guided prompts)
mcp-client --url https://your-erp-server.com --api-key your-key interactive
# Using npx (no installation)
npx kore-erpgateway-mcp --url https://your-erp-server.com call GetCustomer --args '{"id": "123"}'
```
### Programmatic Usage
Use ERP Gateway as a library in your TypeScript/Node.js applications:
```typescript
import { McpClient } from 'kore-erpgateway-mcp';
// Initialize client
const client = new McpClient('https://your-erp-server.com', '/mcp', {
apiKey: 'your-api-key',
timeout: 30000,
retries: 3
});
// Connect to server
await client.initialize();
// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);
// Call a tool
const result = await client.callTool('GetCustomer', {
customerId: '12345'
});
console.log('Customer data:', result);
// Update API key dynamically
client.setApiKey('new-api-key');
```
## Configuration
### MCP Server Options
Both CLI arguments and environment variables are supported:
| CLI Argument | Environment Variable | Default | Description |
|--------------|---------------------|---------|-------------|
| `-u, --url` | `KORE_ERP_URL` | `http://localhost:5000` | Base URL of your ERP Gateway server |
| `-e, --endpoint` | `KORE_ERP_ENDPOINT` | `/mcp` | MCP endpoint path |
| `-k, --api-key` | `KORE_ERP_API_KEY` | - | API key for authentication |
| `-t, --timeout` | `KORE_ERP_TIMEOUT` | `30000` | Request timeout (milliseconds) |
| `-r, --retries` | `KORE_ERP_RETRIES` | `3` | Number of retry attempts |
CLI arguments take precedence over environment variables.
### CLI Commands
| Command | Description |
|---------|-------------|
| `init` | Initialize connection and display server information |
| `list-tools` | List all available ERP tools |
| `call <toolName>` | Call a specific tool with JSON arguments |
| `interactive` | Enter interactive mode with guided prompts |
## Examples
### Example 1: Using Claude with your SAP public cloud
After configuring ERP Gateway as an MCP server in Claude Desktop, you can interact naturally with your SAP system:
```
You: "Show me the details for customer account 12345 from our SAP system"
Claude: [Uses ERP Gateway GetCustomer tool]
"Here are the details for customer 12345 from SAP:
- Company: Acme Corp
- Status: Active
- Account Manager: John Smith
- Credit Limit: $50,000..."
You: "What orders have they placed in the last 30 days?"
Claude: [Uses GetCustomerOrders tool]
"Customer 12345 has 3 orders in the last 30 days:
1. Order #SO-2024-001 - $12,450 (Delivered)
2. Order #SO-2024-015 - $8,200 (In Transit)
3. Order #SO-2024-023 - $3,100 (Processing)..."
```
### Example 2: CLI Automation Script
```bash
#!/bin/bash
# Script to check customer status daily
CUSTOMER_IDS=("12345" "67890" "11223")
for id in "${CUSTOMER_IDS[@]}"; do
echo "Checking customer $id..."
mcp-client --url https://erp.company.com --api-key $API_KEY \
call GetCustomer --args "{\"customerId\": \"$id\"}"
done
```
### Example 3: Custom Integration
```typescript
import { McpClient } from 'kore-erpgateway-mcp';
class ERPService {
private client: McpClient;
constructor() {
this.client = new McpClient(
process.env.ERP_URL!,
'/mcp',
{ apiKey: process.env.ERP_API_KEY }
);
}
async getCustomerWithOrders(customerId: string) {
await this.client.initialize();
const customer = await this.client.callTool('GetCustomer', {
customerId
});
const orders = await this.client.callTool('GetCustomerOrders', {
customerId,
limit: 10
});
return { customer, orders };
}
}
```
## API Reference
### McpClient Class
#### Constructor
```typescript
constructor(
baseUrl: string,
endpoint: string = '/mcp',
options?: {
apiKey?: string;
timeout?: number;
retries?: number;
}
)
```
#### Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `initialize()` | - | `Promise<void>` | Connect to the MCP server and initialize session |
| `listTools()` | - | `Promise<Tool[]>` | Get list of all available ERP tools |
| `callTool(name, args)` | `name: string, args: object` | `Promise<any>` | Execute a specific ERP tool |
| `setApiKey(apiKey)` | `apiKey: string` | `void` | Update the API key for authentication |
### CLI Global Options
| Option | Description |
|--------|-------------|
| `-u, --url <url>` | MCP server URL |
| `-k, --api-key <key>` | API key for authentication |
| `-e, --endpoint <path>` | MCP endpoint path (default: `/mcp`) |
| `-a, --args <json>` | Tool arguments as JSON string (for `call` command) |
## Troubleshooting
Contact us <a href="https://www.linkedin.com/company/compass-ap/" target="_blank">here</a>.
### Connection Issues
**Problem:** Cannot connect to ERP server
```bash
# Verify server is accessible
curl https://your-erp-server.com/mcp
# Check if API key is valid
mcp-client --url https://your-erp-server.com --api-key YOUR_KEY init
```
### Authentication Errors
**Problem:** 401 Unauthorized errors
- Ensure your API key is correct
- Check if the API key has proper permissions
- Verify the key hasn't expired
### Timeout Errors
**Problem:** Requests timing out
```bash
# Increase timeout (in milliseconds)
mcp-client --url https://your-erp-server.com --timeout 60000 list-tools
```
### MCP Server Not Starting in Claude
1. Check Claude Desktop logs for errors
2. Verify the command path is correct
3. Test the server manually:
```bash
kore-erp-mcp-server --url https://your-erp-server.com
```
4. Restart Claude Desktop after configuration changes
### Common Error Messages
| Error | Cause | Solution |
|-------|-------|----------|
| `ECONNREFUSED` | Cannot reach server | Check URL and network connectivity |
| `Invalid API key` | Authentication failure | Verify API key is correct |
| `Tool not found` | Invalid tool name | Run `list-tools` to see available tools |
| `Timeout` | Request took too long | Increase timeout or check server performance |
## Support
- **Enterprise Support:** Contact your Compass AI account representative
- **Technical Documentation:** [Model Context Protocol](https://modelcontextprotocol.io/)
- **API Access:** Request credentials from your Compass AI administrator
- **Issues & Feature Requests:** Report via your organization's support channel
## About Compass Agentic Platform
Compass AI provides enterprise-grade AI agent infrastructure for businesses. ERP Gateway is part of our broader platform that enables secure, intelligent automation across your enterprise systems.
**Learn more:** Contact Compass AI for enterprise licensing and deployment options.
## Related Resources
- [Compass Agentic Platform](https://compassap.ai/)
- [Compass Documentation](https://brightendigital.github.io/kore/)
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Anthropic MCP Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp)
- [Claude Desktop](https://claude.ai/desktop)
---
**Compass Agentic Platform** - Empowering Enterprise AI Automation