SAP OData to MCP Server for BTP🚀

🎯 Project Goal

Transform your SAP S/4HANA or ECC system into a conversational AI interface by exposing all OData services as dynamic MCP tools. This enables natural language interactions with your ERP data:

• "Show me 10 banks" → Automatically queries the Bank entity with $top=10

• "Update bank with ID 1 to have street number 5" → Executes PATCH operation on Bank entity

• "Create a new customer with name John Doe" → Performs POST to Customer entity

• "List all purchase orders from this week" → Applies $filter for date range on PurchaseOrder entity

🏗️ Architecture Overview

graph TB
    A[AI Agent/LLM] --> B[MCP Client]
    B --> C[SAP MCP Server]
    C --> D[SAP BTP Destination]
    D --> E[SAP SAP System]
    
    C --> F[Dynamic Service Discovery]
    F --> G[OData Catalog API]
    C --> H[CRUD Tool Generation]
    H --> I[Entity Metadata Parser]
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style E fill:#e8f5e8

Core Components:

1. 🔍 Service Discovery Engine: Automatically discovers all available OData services from SAP

2. ⚙️ Dynamic Tool Generator: Creates MCP tools for CRUD operations on each discovered entity

3. 🔌 MCP Protocol Layer: Full compliance with MCP 2025-06-18 specification

4. 🌐 HTTP Transport: Session-based Streamable HTTP for web applications

5. 🔐 BTP Integration: Seamless authentication via SAP BTP Destination service

✨ Key Features

🎨 Natural Language to OData

• Smart Query Translation: Converts natural language to proper OData queries

• Context-Aware Operations: Understands entity relationships and constraints

• Parameter Inference: Automatically maps user intent to tool parameters

🔄 Dynamic CRUD Operations

• Read Operations: Entity sets with filtering, sorting, pagination

• Create Operations: New entity creation with validation

• Update Operations: Partial and full entity updates

• Delete Operations: Safe entity deletion with confirmation

🚀 Production-Ready

• Session Management: Automatic session creation and cleanup

• Error Handling: Comprehensive error handling with user-friendly messages

• Logging: Detailed logging for debugging and monitoring

• Security: DNS rebinding protection, CORS, Helmet security

📊 Real-Time Metadata

• Service Catalog: Live discovery of available services

• Entity Schemas: Dynamic schema generation from OData metadata

• Capability Detection: Automatic detection of CRUD capabilities per entity

🏛️ System Architecture

┌─────────────────────┐    ┌───────────────────────────┐    ┌─────────────────────┐
│                     │    │                           │    │                     │
│   🤖 AI Agent       │    │   🖥️  SAP MCP Server     │    │   🏢 SAP            │
│   - Claude          │◄──►│   - Service Discovery     │◄──►│   - OData Services  │
│   - GPT-4           │    │   - CRUD Tool Registry    │    │   - Business Logic  │
│   - Local LLMs      │    │   - Session Management    │    │   - Master Data     │
│                     │    │   - BTP Authentication    │    │                     │
└─────────────────────┘    └───────────────────────────┘    └─────────────────────┘
                                           │                                       
                                           ▼                                       
                           ┌───────────────────────────┐                          
                           │                           │                          
                           │   ☁️  SAP BTP Platform    │                          
                           │   - Destination Service   │                          
                           │   - Connectivity Service  │                          
                           │   - XSUAA Security        │                          
                           │                           │                          
                           └───────────────────────────┘                          

🎯 Use Cases

📈 Business Intelligence Queries

User: "Show me top 10 customers by revenue this quarter"
→ Tool: r-CustomerService-Customer
→ Parameters: $filter, $orderby, $top

📝 Data Maintenance

User: "Update supplier ABC123 to have status 'Active'"
→ Tool: u-SupplierService-Supplier
→ Parameters: SupplierId="ABC123", Status="Active"

📊 Analytical Insights

User: "How many open purchase orders are there?"
→ Tool: r-PurchaseOrderService-PurchaseOrder
→ Parameters: $filter=Status eq 'Open'&$count=true

🔧 System Administration

User: "List all inactive users in the system"
→ Tool: r-UserService-User
→ Parameters: $filter=Status eq 'Inactive'

🛠️ Installation & Setup

Prerequisites

• Node.js 18.x or higher

• SAP S/4HANA or ECC system with OData services enabled

• SAP BTP account with Destination and Connectivity services

• TypeScript knowledge for customization

🚀 Usage Examples

Natural Language Queries

The MCP server automatically translates these natural language commands to the appropriate tool calls:

📋 Available Tools

Tool Naming Convention

{operationAbbreviation}-{serviceId}-{entityName}

Where operationAbbreviation is:

• r: read (query entities or get single entity)

• c: create (create new entity)

• u: update (update existing entity)

• d: delete (delete entity)

Examples:

• r-API_BUSINESS_PARTNER-BusinessPartner

• c-API_CUSTOMER_MATERIAL_SRV-CustomerMaterial

• u-API_SALES_ORDER_SRV-SalesOrder

• d-API_SALES_ORDER_SRV-SalesOrder

CRUD Operations

Protocol Version: 2025-06-18

Supported Capabilities:

• ✅ Tools with listChanged notifications

• ✅ Resources with listChanged notifications

• ✅ Logging with level control

• ✅ Session Management for HTTP transport

• ✅ Error Handling with proper error codes

Transport Support

• ✅ Streamable HTTP (recommended)

• ✅ Stdio for command line usage

• ✅ Session-based with automatic cleanup

• ✅ DNS Rebinding Protection

🔒 Security & Authentication

SAP BTP Integration

• Uses BTP Destination service for S/4HANA or ECC authentication

• Supports Principal Propagation and OAuth2

• Automatic token refresh and session management

• Secure credential storage in BTP

HTTP Security

• Helmet.js security headers

• CORS protection with configurable origins

• DNS rebinding attack prevention

• Request rate limiting (configurable)

Session Security

• Automatic session expiration (24h default)

• Secure session ID generation

• Session cleanup on server restart

• Memory leak prevention

📚 API Reference

Health Check

GET /health
{
  "status": "healthy",
  "activeSessions": 3,
  "discoveredServices": 25,
  "version": "2.0.0"
}

Server Info

GET /mcp
{
  "name": "btp-sap-odata-to-mcp-server",
  "protocol": { "version": "2025-06-18" },
  "capabilities": { "tools": {}, "resources": {} },
  "features": ["Dynamic service discovery", "CRUD operations"],
  "activeSessions": 3
}

Documentation

GET /docs
{
  "title": "SAP MCP Server API",
  "endpoints": {...},
  "mcpCapabilities": {...},
  "usage": {...}
}

🎬 Demo

See the MCP server in action:

⚙️ Environment Variable: Disable ReadEntity Tool Registration

To disable registration of the ReadEntity tool for all entities in all services, set the following in your .env file:

DISABLE_READ_ENTITY_TOOL=true

This will prevent registration of the ReadEntity tool for all entities and services.

⚡ Quick Start

• For local development and testing, see LOCAL_RUN.md

• For deployment to SAP BTP, see DEPLOYMENT.md