midasol/sap-mcp-server

SAP MCP - SAP Gateway Integration via Model Context Protocol

Complete MCP server for SAP Gateway integration, providing modular tools for SAP OData operations with AI agents.

📑 Table of Contents

• 🎯 Project Overview
• ⚡ Quick Start
• 📐 Architecture
  • System Overview
  • Component Details
  • Data Flow
  • Tool Execution Flow
  • Security Architecture
• 📦 Repository Structure
• ✨ Features
• 🎓 SAP SFLIGHT Demo Scenario
  • Scenario Overview
  • OData Service Creation Guide
• 🚀 Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Run Server
• 🤖 Integration with Gemini CLI
  • Prerequisites
  • Install Gemini CLI
  • Authenticate Gemini CLI
  • Register SAP MCP Server
  • Start Using
  • Advanced Configuration
  • Troubleshooting
  • Available Tools
  • Example Workflows
• 🔧 Available Tools
  • SAP Authenticate
  • SAP Query
  • SAP Get Entity
  • SAP List Services
  • Adding a New Tool
• 📚 Usage Examples
• 🔒 Security
• 📖 Documentation
• 📝 License
• 🙏 Acknowledgments

🎯 Project Overview

Production-ready MCP (Model Context Protocol) server that enables AI agents and applications to interact with SAP Gateway systems through a clean, modular architecture. Built for reliability, security, and developer experience.

Current Status: ✅ Production Ready (All 5 phases completed)

Key Highlights

• 🔐 Secure SAP Integration: Enterprise-grade authentication and SSL/TLS support
• 🛠️ 4 Modular Tools: Authentication, query, entity retrieval, service discovery
• 🚀 Stdio Transport: Production-ready MCP server
• 📊 Structured Logging: JSON and console formats with performance metrics
• ✅ Validated Inputs: Comprehensive OData and security validation
• 🧪 Well-Tested: 56% coverage, 44/45 tests passing (98% success rate)

⚡ Quick Start

Get up and running with SAP MCP in 5 minutes:

# 1. Clone and navigate to project
git clone <repository-url>
cd sap-mcp

# 2. Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
cd packages/server
pip install -e .

# 3. Configure SAP connection
cd ../..
cp .env.server.example .env.server
# Edit .env.server with your SAP credentials

# 4. Configure services
cp packages/server/config/services.yaml.example packages/server/config/services.yaml
# Edit services.yaml with your SAP services

# 5. Run the server
sap-mcp-server-stdio

Next Steps:

• 📖 See Getting Started for detailed installation instructions
• 🤖 Check Integration with Gemini CLI to connect with AI agents
• 🔧 Explore Available Tools for API documentation

📐 Architecture

System Overview

Component Details

Data Flow: Order Query Example

Tool Execution Flow

Security Architecture

📦 Repository Structure

sap-mcp/
├── packages/
│   └── server/                          ✅ Production-Ready MCP Server
│       ├── src/sap_mcp_server/
│       │   ├── core/                    # SAP client & auth (4 files)
│       │   │   ├── __init__.py          # Module initialization
│       │   │   ├── sap_client.py        # OData operations
│       │   │   ├── auth.py              # Credential management
│       │   │   └── exceptions.py        # Custom exceptions
│       │   ├── config/                  # Configuration (4 files)
│       │   │   ├── __init__.py          # Module initialization
│       │   │   ├── settings.py          # Environment config
│       │   │   ├── loader.py            # YAML loader
│       │   │   └── schemas.py           # Pydantic models
│       │   ├── protocol/                # MCP protocol (2 files)
│       │   │   ├── __init__.py          # Module initialization
│       │   │   └── schemas.py           # Request/Response schemas
│       │   ├── tools/                   # 4 modular SAP tools (6 files)
│       │   │   ├── __init__.py          # Tool registry
│       │   │   ├── base.py              # Tool base class
│       │   │   ├── auth_tool.py         # Authentication
│       │   │   ├── query_tool.py        # OData queries
│       │   │   ├── entity_tool.py       # Entity retrieval
│       │   │   └── service_tool.py      # Service discovery
│       │   ├── transports/              # Transport layer (2 files)
│       │   │   ├── __init__.py          # Module initialization
│       │   │   └── stdio.py             # Stdio transport ✅
│       │   ├── utils/                   # Utilities (3 files)
│       │   │   ├── __init__.py          # Module initialization
│       │   │   ├── logger.py            # Structured logging
│       │   │   └── validators.py        # Input validation
│       │   └── __init__.py              # Package initialization
│       ├── config/                      # Server configuration
│       │   ├── services.yaml            # SAP services config
│       │   └── services.yaml.example    # Configuration template
│       ├── tests/                       # Test suite (7 files, 56% coverage)
│       │   ├── __init__.py              # Test package initialization
│       │   ├── conftest.py              # Pytest fixtures
│       │   ├── unit/                    # Unit tests
│       │   │   ├── __init__.py          # Unit test package
│       │   │   ├── test_base.py         # Base tool tests
│       │   │   └── test_validators.py   # Validator tests
│       │   └── integration/             # Integration tests
│       │       ├── __init__.py          # Integration test package
│       │       └── test_tool_integration.py  # Tool integration tests
│       ├── pyproject.toml               # Package configuration
│       └── README.md                    # Server package documentation
│
├── docs/                                # Documentation
│   ├── architecture/                    # Architecture documentation
│   │   └── server.md                    # Server architecture
│   └── guides/                          # User guides
│       ├── configuration.md             # Configuration guide
│       ├── deployment.md                # Deployment guide
│       ├── troubleshooting.md           # Troubleshooting guide
│       ├── odata-service-creation-flight-demo.md  # OData service creation
│       └── sfight-demo-guide.md         # SFLIGHT demo guide
│
├── examples/                            # Example applications
│   ├── basic/                           # Basic examples
│   │   └── stdio_client.py              # Stdio client example
│   ├── chatbot/                         # Chatbot examples
│   │   └── order_inquiry_chatbot.py     # Order inquiry chatbot
│   └── README.md                        # Examples documentation
│
├── scripts/                             # Development scripts
│   ├── create_structure.sh              # Project structure creation
│   ├── migrate_code.sh                  # Code migration script
│   └── update_imports.py                # Import update script
│
├── .env.server.example                  # Environment template
├── README.md                            # Main documentation (English)
├── README.ja.md                         # Japanese documentation
├── README.ko.md                         # Korean documentation
├── README.th.md                         # Thai documentation
├── README.zh-TW.md                      # Traditional Chinese documentation
└── README.zh-CN.md                      # Simplified Chinese documentation

✨ Features

Core Capabilities

Developer Experience

• ✅ Modular Architecture: One tool per file
• ✅ Type Safety: Full type hints
• ✅ Documentation: Comprehensive guides
• ✅ Easy Setup: pip install -e .
• ✅ Hot Reload: Development mode
• ✅ Example Apps: 3 working examples

🎓 SAP SFLIGHT Demo Scenario

Scenario Overview

For convenience, this project is based on the SAP SFLIGHT Demo dataset.

The SFLIGHT dataset is a sample database provided by SAP that includes data for flight schedules, airlines, airports, and bookings. It's an excellent resource for testing and demonstrating data modeling and service creation.

This guide assumes you have an OData service exposing this dataset. The goal is to connect our SAP MCP server to this service and interact with it using AI agents or other clients.

Official SAP Documentation:

• SAP Documentation - Flight Model
• SAP Help Portal - Flight Model

OData Service Creation Guide

This guide provides a step-by-step walkthrough for creating an OData service in an SAP system using the SAP Gateway Service Builder (SEGW) to expose the Flight scenario data available in SAP S/4HANA Fully Activated Appliance (FAA) version.

Scenario Overview

• Goal: Expose flight schedules, bookings, and related master data via an OData service.
• Scenario Data Needs: Flight schedules, dates, times, airport details, airline details, passenger details, pricing, etc.
• SAP Tables Involved: SFLIGHT, SPFLI, SCARR, SAIRPORT, SBOOK, SCUSTOM.

Steps to Create the OData Service in SEGW

1. Access SAP Gateway Service Builder

Navigate to the SAP transaction code SEGW.

2. Create a New Project

1. Click the "Create Project" button.
2. Project Name: Assign a name (e.g., Z_TRAVEL_RECOMMENDATIONS_SRV).
3. Description: Provide a meaningful description.
4. Package: Assign to a package (e.g., $TMP for local development or a transportable package).

3. Import Data Model from DDIC Structures

This step defines your OData entities based on the underlying SAP tables.

1. Right-click on the "Data Model" folder within your project.
2. Select "Import" -> "DDIC Structure".
3. Repeat the import process for each required table, specifying the Entity Type Name and selecting the necessary fields.

Action Required: Ensure the Key fields are correctly marked during the import process.

4. Define Associations and Navigation Properties

Associations link entities based on key fields. Navigation Properties allow client applications to easily traverse these relationships (e.g., using $expand).

Logical Relationships:

• 1:N: Airline <-> Flights, Airline <-> Connections, Connection <-> Flights, Flight <-> Bookings, Passenger <-> Bookings.
• N:1: Connection <-> Origin Airport, Connection <-> Destination Airport.

Steps to Create an Association:

1. Right-click on "Data Model" -> "Create" -> "Association".
2. Define the Association Name, Principal Entity (the 'one' side), Dependent Entity (the 'many' side), and Cardinality (e.g., 1:N).
3. On the next screen, Specify Key Mapping by matching the key fields between the Principal and Dependent entities.

Specific Associations to Create:

Navigation Properties to Create:

5. Generate Runtime Objects

1. Click the "Generate Runtime Objects" button (magic wand icon).
2. This generates the ABAP classes: Model Provider Class (MPC) and Data Provider Class (DPC).
3. Accept or adjust the default class names.

6. Implement Data Provider Class (DPC) Methods

The generated DPC extension class (e.g., ZCL_Z_TRAVEL_RECOM_DPC_EXT) is used for custom logic.

• If direct table mapping is sufficient, the base implementation may suffice.
• For custom filtering, joins, calculations, or complex Read/Create/Update/Delete (CRUD) operations, you must redefine methods like *_GET_ENTITY (single record) and *_GET_ENTITYSET (collection) in the DPC extension class.

Here is an example of method AIRLINESET_GET_ENTITYSET:

METHOD airlineset_get_entityset.
  DATA: lt_airlines TYPE TABLE OF scarr,
        ls_airline TYPE scarr,
        lv_filter_string TYPE string.

  TRY.
      lv_filter_string = io_tech_request_context->get_filter( )->get_filter_string( ).
    CATCH cx_sy_itab_line_not_found.
      CLEAR lv_filter_string.
  ENDTRY.

  " TODO: Apply filtering based on lv_filter_string"
  IF lv_filter_string IS NOT INITIAL.
    SELECT * FROM scarr INTO TABLE lt_airlines WHERE (lv_filter_string).
  ELSE.
    SELECT * FROM scarr INTO TABLE lt_airlines.
  ENDIF.

  LOOP AT lt_airlines INTO ls_airline.
    APPEND ls_airline TO et_entityset.
  ENDLOOP.
ENDMETHOD.

7. Register the Service

1. Go to transaction /IWFND/MAINT_SERVICE.
2. Click "Add Service".
3. Enter the System Alias for your backend system (e.g., LOCAL).
4. Search for your service by the Technical Service Name (e.g., Z_TRAVEL_RECOMMENDATIONS_SRV).
5. Select the service and click "Add Selected Services".
6. Assign a package and confirm.

8. Activate and Test the Service

1. In /IWFND/MAINT_SERVICE, find your newly registered service.
2. Ensure the ICF node is active (green light). If not, select the service, go to "ICF Node" -> "Activate".
3. Select the service and click the "SAP Gateway Client" button.
4. Testing in Gateway Client:
   • Test entity collection retrieval: Click "EntitySets", select an EntitySet (e.g., AirlineCollection), and click "Execute".
   • Test OData features: Try query options like $filter, and especially $expand to verify the navigation properties are working (e.g., /FlightSet(key)?$expand=ToAirline).

9. Note the Service URL

The final OData service URL will be visible in the Gateway Client. It typically follows the structure:

/sap/opu/odata/sap/Z_TRAVEL_RECOMMENDATIONS_SRV/. This URL is what client applications (like Fiori or custom mobile apps) will use to consume the SFLIGHT data.

🚀 Getting Started

Prerequisites for MCP Server

System Requirements

• Python 3.11 or higher
• pip (Python package installer)
• Git (for cloning repository)
• SAP Gateway access credentials
• Virtual environment support

Installing Python

# Search for "Python 3.11" or "Python 3.12" in Microsoft Store
# Or download from python.org

python --version
# Should show: Python 3.11.x or higher

pip --version
# Should show: pip 23.x.x or higher

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11
# or
brew install python@3.12

python3 --version
# Should show: Python 3.11.x or higher

pip3 --version
# Should show: pip 23.x.x or higher

# Update package list
sudo apt update

# Install Python 3.11+
sudo apt install python3.11 python3.11-venv python3-pip

# Or for latest Python
sudo apt install python3 python3-venv python3-pip

# Install Python 3.11+
sudo dnf install python3.11 python3-pip

# Or
sudo yum install python3 python3-pip

sudo pacman -S python python-pip

python3 --version
# Should show: Python 3.11.x or higher

pip3 --version
# Should show: pip 23.x.x or higher

1. Installation

Step-by-Step Installation

# Clone repository
git clone <repository-url>
cd sap-mcp

# Create virtual environment
python -m venv .venv

# Activate virtual environment
.venv\Scripts\activate
# Or in PowerShell:
# .venv\Scripts\Activate.ps1

# If you get execution policy error in PowerShell:
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Verify activation (you should see (.venv) in prompt)
# (.venv) PS C:\path\to\sap-mcp>

# Install server package
cd packages\server
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

# Verify installation
sap-mcp-server-stdio --help

# Clone repository
git clone <repository-url>
cd sap-mcp

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Verify activation (you should see (.venv) in prompt)
# (.venv) user@macbook sap-mcp %

# Install server package
cd packages/server
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

# Verify installation
sap-mcp-server-stdio --help

# Check installation path (useful for Gemini CLI setup)
which sap-mcp-server-stdio
# Example output: /Users/username/sap-mcp/.venv/bin/sap-mcp-server-stdio

# Clone repository
git clone <repository-url>
cd sap-mcp

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Verify activation (you should see (.venv) in prompt)
# (.venv) user@linux:~/sap-mcp$

# Install server package
cd packages/server
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

# Verify installation
sap-mcp-server-stdio --help

# Check installation path (useful for Gemini CLI setup)
which sap-mcp-server-stdio
# Example output: /home/username/sap-mcp/.venv/bin/sap-mcp-server-stdio

2. Configuration

The SAP MCP server requires two configuration files:

1. .env.server: SAP connection credentials (one SAP system)
2. services.yaml: SAP Gateway Services and authentication settings

2.1. SAP Connection Configuration (.env.server)

⚠️ IMPORTANT: As of v0.2.0, .env.server has been consolidated to the project root directory only. The previous packages/server/.env.server location is no longer supported.

File Location: .env.server must be in the project root directory.

sap-mcp/
├── .env.server              ← Configuration file (ONLY location - create here)
├── .env.server.example      ← Example template
├── packages/
│   └── server/
└── README.md

Setup Steps:

# Navigate to project root
cd C:\path\to\sap-mcp

# Copy environment template
copy .env.server.example .env.server

# Edit configuration with your SAP credentials using Notepad
notepad .env.server

# Or use your preferred editor:
# code .env.server (VS Code)
# notepad++ .env.server (Notepad++)

# Note: File permissions are managed differently on Windows
# Ensure the file is not in a public folder
# Right-click .env.server > Properties > Security to restrict access

# Navigate to project root
cd /path/to/your/sap-mcp

# Copy environment template
cp .env.server.example .env.server

# Edit configuration with your SAP credentials
nano .env.server
# Or use your preferred editor:
# vim .env.server
# code .env.server (VS Code)
# open -a TextEdit .env.server

# Set proper permissions (recommended for security)
chmod 600 .env.server

# Verify permissions
ls -la .env.server
# Should show: -rw------- (only owner can read/write)

# Navigate to project root
cd /path/to/your/sap-mcp

# Copy environment template
cp .env.server.example .env.server

# Edit configuration with your SAP credentials
nano .env.server
# Or use your preferred editor:
# vim .env.server
# code .env.server (VS Code)
# gedit .env.server (GNOME)

# Set proper permissions (REQUIRED for security)
chmod 600 .env.server

# Verify permissions
ls -la .env.server
# Should show: -rw------- (only owner can read/write)

# Optional: Verify file is not world-readable
stat .env.server

Required Environment Variables:

# SAP System Connection (Single SAP System)
SAP_HOST=your-sap-host.com          # SAP Gateway hostname
SAP_PORT=443                         # HTTPS port (usually 443 or 8443)
SAP_USERNAME=your-username           # SAP user ID
SAP_PASSWORD=your-password           # SAP password
SAP_CLIENT=100                       # SAP client number (e.g., 100, 800)

# Security Settings
SAP_VERIFY_SSL=false                 # Enable SSL certificate verification (recommended)
SAP_TIMEOUT=30                       # Request timeout in seconds

# Optional: Connection Pooling
SAP_MAX_CONNECTIONS=10               # Maximum concurrent connections (optional)
SAP_RETRY_ATTEMPTS=3                 # Number of retry attempts on failure (optional)

Security Best Practices:

• ✅ Never commit .env.server to version control (already in .gitignore)
• ✅ Use strong, unique passwords
• ✅ Enable SSL verification in production (SAP_VERIFY_SSL=true)
• ✅ Restrict file permissions: chmod 600 .env.server

2.2. SAP Gateway Services Configuration (services.yaml)

Configure SAP Gateway Services (OData services) that the MCP server can access.

Location: packages/server/config/services.yaml

# Copy example configuration
cp packages/server/config/services.yaml.example packages/server/config/services.yaml

# Edit service configuration
vim packages/server/config/services.yaml

Basic Configuration Example:

# Gateway URL configuration
gateway:
  # Base URL pattern for OData services
  base_url_pattern: "https://{host}:{port}/sap/opu/odata"

  # Metadata endpoint suffix
  metadata_suffix: "/$metadata"

  # Service catalog path
  service_catalog_path: "/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ServiceCollection"

  # Authentication endpoint configuration
  auth_endpoint:
    # RECOMMENDED: Use catalog metadata (works without specific service)
    use_catalog_metadata: true

    # Optional: Use specific service for authentication (if catalog unavailable)
    # use_catalog_metadata: false
    # service_id: Z_TRAVEL_RECOMMENDATIONS_SRV
    # entity_name: AirlineSet

# SAP OData Services
services:
  # SFLIGHT Demo Service (Travel Recommendations)
  - id: Z_TRAVEL_RECOMMENDATIONS_SRV
    name: "Travel Recommendations Service (SFLIGHT)"
    path: "/SAP/Z_TRAVEL_RECOMMENDATIONS_SRV"
    version: v2
    description: "OData service for the SFLIGHT demo dataset."
    entities:
      - name: AirlineSet
        key_field: CARRID
        description: "Airlines (e.g., LH, AA)"
        default_select:
          - CARRID
          - CARRNAME
          - CURRCODE
          - URL
      - name: AirportSet
        key_field: ID
        description: "Airports (e.g., FRA, JFK)"
        default_select:
          - ID
          - NAME
          - CITY
          - COUNTRY
      - name: FlightSet
        key_field: "CARRID='{CARRID}',CONNID='{CONNID}',FLDATE=datetime'{FLDATE}'"
        description: "Specific flights on a given date"
      - name: BookingSet
        key_field: "CARRID='{CARRID}',CONNID='{CONNID}',FLDATE=datetime'{FLDATE}',BOOKID='{BOOKID}'"
        description: "Individual flight bookings"

    # Optional: Custom headers for this service
    custom_headers: {}

2.3. Authentication Endpoint Options

The auth_endpoint configuration controls how the MCP server authenticates with SAP.

Option 1: Catalog Metadata (Recommended)

gateway:
  auth_endpoint:
    use_catalog_metadata: true

Advantages:

• ✅ Works without requiring specific SAP Gateway Services
• ✅ More flexible and portable across SAP systems
• ✅ Service-independent authentication
• ✅ No dependency on custom service deployment

Authentication Flow:

• CSRF Token: /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ServiceCollection
• Validation: /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/$metadata

Note: /sap/opu/odata/IWFND/CATALOGSERVICE should be activated in Tcode SICF

Option 2: Service-Specific Authentication

gateway:
  auth_endpoint:
    use_catalog_metadata: false
    service_id: Z_TRAVEL_RECOMMENDATIONS_SRV    # Must match a service ID below
    entity_name: AirlineSet                     # Must be an entity in that service

Advantages:

• ✅ Explicit service-based authentication
• ✅ Works when catalog service is unavailable (rare)

Disadvantages:

• ❌ Requires the specified service to be deployed
• ❌ Less flexible if service changes
• ❌ Must update config if service name changes

Authentication Flow:

• CSRF Token: /SAP/Z_TRAVEL_RECOMMENDATIONS_SRV/AirlineSet
• Validation: /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/$metadata

Recommendation: Use Option 1 (Catalog Metadata) unless you have a specific reason to use a particular service for authentication.

3. Run Server

# Activate virtual environment
.venv\Scripts\activate
# Or in PowerShell:
# .venv\Scripts\Activate.ps1

# Run stdio server (recommended)
sap-mcp-server-stdio

# Or directly with Python
python -m sap_mcp_server.transports.stdio

# To deactivate when done
deactivate

# Activate virtual environment
source .venv/bin/activate

# Run stdio server (recommended)
sap-mcp-server-stdio

# Or directly with Python
python3 -m sap_mcp_server.transports.stdio

# To deactivate when done
deactivate

# Activate virtual environment
source .venv/bin/activate

# Run stdio server (recommended)
sap-mcp-server-stdio

# Or directly with Python
python3 -m sap_mcp_server.transports.stdio

# To deactivate when done
deactivate

🤖 Integration with Gemini CLI

📖 Official Documentation: For more information about Gemini CLI, visit https://geminicli.com/

Prerequisites

• Node.js 18+ and npm installed
• SAP MCP Server installed (see Quick Start above)
• Google Account for Gemini API access

1. Install Gemini CLI

# Install Gemini CLI globally
npm install -g @google/gemini-cli

# Verify installation
gemini --version

2. Authenticate Gemini CLI

Option A: Using Gemini API Key (Recommended for Getting Started)

1. Get your API key from Google AI Studio
2. Set the environment variable:

export GEMINI_API_KEY="your-api-key-here"

Option B: Using Google Cloud (For Production)

# Install Google Cloud CLI first
gcloud auth application-default login

# Set your project
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

3. Register SAP MCP Server

Method A: Using Absolute Path (Recommended for Virtual Environments)

If you installed the server in a virtual environment, use the absolute path to the executable:

1. Find the absolute path:

# Navigate to your SAP MCP directory
cd /path/to/your/sap-mcp

# Get the absolute path
pwd
# Example output: /path/to/your/sap-mcp

2. Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "cwd": "/path/to/your/sap-mcp",
      "description": "SAP Gateway MCP Server for OData integration",
      "timeout": 30000,
      "trust": false
    }
  }
}

Replace /path/to/your/sap-mcp with your actual project path.

📝 Note: The cwd (current working directory) parameter is ABSOLUTELY CRITICAL for .env.server file discovery. You MUST set this to your project root directory (e.g., /Users/username/projects/sap-mcp). If omitted or incorrect, the server will fail to load your credentials.

3. Verify the path:

# Test the command works
/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio --help

# Verify registration
gemini mcp list
# Expected: ✓ sap-server: ... (stdio) - Connected

Method B: Using CLI Command (If installed globally)

If sap-mcp-server-stdio is in your system PATH:

# Register the server
gemini mcp add sap-server sap-mcp-server-stdio

# Verify registration
gemini mcp list

Note: This method only works if you added the virtual environment to your PATH or installed the package globally.

Method C: Using Python Module Path

Alternative approach using Python module:

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/python",
      "args": ["-m", "sap_mcp_server.transports.stdio"],
      "cwd": "/path/to/your/sap-mcp/packages/server",
      "description": "SAP Gateway MCP Server",
      "timeout": 30000,
      "trust": false
    }
  }
}

4. Start Using SAP MCP with Gemini CLI

# Start Gemini CLI
gemini

# Check MCP server status
> /mcp

# View available SAP tools
> /mcp desc

# Example: Query SAP airlines
> Use the SAP tools to authenticate and show me all airlines

# Example: List available SAP services
> What SAP services are available?

# Example: Get airport details
> Retrieve details for Frankfurt airport (FRA)

Advanced Configuration

Enable Auto-Approval for Trusted Server

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "trust": true,
      "timeout": 30000
    }
  }
}

Note: Set "trust": true to skip approval prompts for each tool call. Only enable for trusted servers.

Filter Specific Tools

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "includeTools": ["sap_authenticate", "sap_query"],
      "excludeTools": ["sap_list_services"],
      "timeout": 30000
    }
  }
}

Use Cases:

• includeTools: Only allow specific tools (whitelist)
• excludeTools: Block specific tools (blacklist)
• Cannot use both simultaneously

Add Environment Variables (Optional)

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "env": {
        "SAP_HOST": "${SAP_HOST}",
        "SAP_USERNAME": "${SAP_USERNAME}",
        "SAP_PASSWORD": "${SAP_PASSWORD}"
      },
      "timeout": 30000
    }
  }
}

Note: Environment variables in settings.json override values from .env.server. Not recommended for security reasons - prefer using .env.server file instead.

Increase Timeout for Slow Networks

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "timeout": 60000,  // 60 seconds (default: 30000)
      "trust": false
    }
  }
}

When to increase:

• Slow network connections
• Large data queries
• Complex SAP operations
• Frequent timeout errors

Troubleshooting

Problem: Server shows "Disconnected" status

# Check MCP server status
gemini mcp list
# If you see: ✗ sap-server: sap-mcp-server-stdio (stdio) - Disconnected

Solution 1: Use absolute path (Most Common)

The command is likely in a virtual environment. Update ~/.gemini/settings.json:

{
  "mcpServers": {
    "sap-server": {
      "command": "/path/to/your/sap-mcp/.venv/bin/sap-mcp-server-stdio",
      "description": "SAP Gateway MCP Server",
      "timeout": 30000,
      "trust": false
    }
  }
}

Find your absolute path:

# Navigate to SAP MCP directory
cd /path/to/your/sap-mcp

# Get full path
pwd
# Example: /path/to/your/sap-mcp

# Verify command exists
ls -la .venv/bin/sap-mcp-server-stdio

Problem: Command not found in PATH

# Test server directly
sap-mcp-server-stdio
# Error: command not found

# Check if command exists
which sap-mcp-server-stdio
# Returns: command not found

Solution 2: Check virtual environment

# Check if virtual environment exists
ls -la .venv/bin/sap-mcp-server-stdio

# If exists, use absolute path in settings.json
# If not exists, reinstall:
cd packages/server
pip install -e .

Problem: Authentication Errors or .env.server not found

# Verify .env.server exists in PROJECT ROOT (not in packages/server/)
cat .env.server

# Required fields:
# SAP_HOST=your-host
# SAP_PORT=443
# SAP_USERNAME=your-username
# SAP_PASSWORD=your-password
# SAP_CLIENT=100

Solution 3: Verify file location and credentials

# 1. Check if .env.server is in project root
ls -la .env.server
# Should exist in: /path/to/sap-mcp/.env.server

# 2. Ensure Gemini CLI settings.json has "cwd" parameter
cat ~/.gemini/settings.json
# Must include: "cwd": "/path/to/sap-mcp"

# 3. Test authentication manually
source .venv/bin/activate
python -c "from sap_mcp_server.config.settings import get_connection_config; print(get_connection_config())"

Common Issues:

1. "Field required" errors: .env.server is not being loaded. Verify:

   • File exists in project root: /path/to/your/sap-mcp/.env.server
   • Gemini CLI settings.json has correct cwd parameter
   • File has proper permissions: chmod 600 .env.server

2. 401 Unauthorized errors: Fixed in v0.2.1 (2025-01-22)

   • Previous Issue: SAP Gateway was rejecting requests without sap-client parameter
   • Current Status: Automatically handled - all requests include sap-client parameter
   • Verification: Ensure you have updated to v0.2.1 or later
   • Manual Check: Authentication should now succeed with valid credentials

Problem: Need to re-register server

# Remove existing server configuration
rm ~/.gemini/settings.json

# Or edit manually to remove sap-server entry

Solution 4: Clean re-registration

# Method 1: Edit settings directly
vim ~/.gemini/settings.json

# Method 2: Use absolute path (recommended)
# Follow "Method A: Using Absolute Path" in section 3 above

Quick Diagnostic Steps

1. Check server executable:

/path/to/sap-mcp/.venv/bin/sap-mcp-server-stdio --help
# Should show server startup messages

2. Check Gemini CLI settings:

cat ~/.gemini/settings.json | grep -A 5 "sap-server"
# Verify "command" path is correct

3. Test connection:

gemini mcp list
# Should show: ✓ sap-server: ... - Connected

4. Test in Gemini CLI:

gemini
> /mcp
> /mcp desc
# Should list SAP tools

Available SAP Tools in Gemini CLI

Once registered, you can use these SAP tools through natural language:

Example Workflows

1. Flight Inquiry Workflow

gemini

> Connect to SAP and find all Lufthansa flights
# Gemini will:
# 1. Call sap_authenticate
# 2. Call sap_query on FlightSet with filter "CARRID eq 'LH'"
# 3. Format and present the results

2. Airport Analysis

> Get details for Frankfurt airport and show me available connections
# Gemini will:
# 1. Authenticate
# 2. Call sap_get_entity for 'FRA' on AirportSet
# 3. Call sap_query on ConnectionSet
# 4. Present insights

3. Service Discovery

> What SAP services and entity sets are available in the system?
# Gemini will:
# 1. Call sap_list_services
# 2. Format the service catalog

🔧 Available Tools

1. SAP Authenticate

Authenticate with SAP Gateway system using credentials from .env.server.

Request:

{
  "name": "sap_authenticate",
  "arguments": {}
}

Response:

{
  "success": true,
  "session_id": "abc123...",
  "message": "Successfully authenticated with SAP Gateway",
  "host": "example.sap.corp",
  "client": "100"
}

2. SAP Query

Query SAP entities with OData filters, selection, pagination.

Request:

{
  "name": "sap_query",
  "arguments": {
    "service": "Z_TRAVEL_RECOMMENDATIONS_SRV",
    "entity_set": "AirlineSet",
    "filter": "CARRID eq 'LH'",
    "select": "CARRID,CARRNAME,CURRCODE",
    "top": 10,
    "skip": 0,
    "format": "json_compact"
  }
}

Parameters:

Output Format Options:

Response (format: "json_compact" - default):

{
  "results": [
    {
      "CARRID": "LH",
      "CARRNAME": "Lufthansa",
      "CURRCODE": "EUR"
    }
  ],
  "count": 1
}

Response (format: "json" - raw):

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "...",
          "uri": "...",
          "type": "Z_TRAVEL_RECO_SRV.Airline"
        },
        "CARRID": "LH",
        "CARRNAME": "Lufthansa",
        "CURRCODE": "EUR",
        "ToFlight": { "__deferred": { "uri": "..." } }
      }
    ]
  }
}

💡 Recommendation: When integrating with AI agents, use the json_compact format (default) to significantly reduce token usage.

3. SAP Get Entity

Retrieve a specific entity by key.

Request:

{
  "name": "sap_get_entity",
  "arguments": {
    "service": "Z_TRAVEL_RECOMMENDATIONS_SRV",
    "entity_set": "AirportSet",
    "entity_key": "'FRA'"
  }
}

Response:

{
  "success": true,
  "service": "Z_TRAVEL_RECOMMENDATIONS_SRV",
  "entity_set": "AirportSet",
  "entity_key": "'FRA'",
  "key_field": "ID",
  "data": {
    "d": {
      "ID": "FRA",
      "NAME": "Frankfurt International",
      "CITY": "Frankfurt",
      "COUNTRY": "DE",
      "TIME_ZONE": "CET"
    }
  }
}

4. SAP List Services

List all available SAP services from configuration.

Request:

{
  "name": "sap_list_services",
  "arguments": {}
}

Response:

{
  "success": true,
  "count": 1,
  "services": [
    {
      "id": "Z_TRAVEL_RECOMMENDATIONS_SRV",
      "name": "Travel Recommendations Service (SFLIGHT)",
      "path": "/SAP/Z_TRAVEL_RECOMMENDATIONS_SRV",
      "version": "v2",
      "description": "OData service for the SFLIGHT demo dataset.",
      "entities": [
        {
          "name": "AirlineSet",
          "key_field": "CARRID",
          "description": "Airlines (e.g., LH, AA)"
        },
        {
          "name": "AirportSet",
          "key_field": "ID",
          "description": "Airports (e.g., FRA, JFK)"
        }
      ]
    }
  ],
  "source": "services.yaml configuration"
}

5. Adding a New Tool

1. Create Tool File: packages/server/src/sap_mcp_server/tools/my_tool.py

from .base import MCPTool

class MyNewTool(MCPTool):
    @property
    def name(self) -> str:
        return "my_new_tool"

    @property
    def description(self) -> str:
        return "Description of my new tool"

    @property
    def input_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "param": {"type": "string"}
            },
            "required": ["param"]
        }

    async def execute(self, params: dict) -> dict:
        # Implementation
        return {"result": "success"}

2. Register Tool: Update packages/server/src/sap_mcp_server/tools/__init__.py

from .my_tool import MyNewTool

# Add to registry
tool_registry.register(MyNewTool())

3. Add Tests: tests/unit/test_my_tool.py

import pytest
from sap_mcp_server.tools.my_tool import MyNewTool

@pytest.mark.asyncio
async def test_my_tool():
    tool = MyNewTool()
    result = await tool.execute({"param": "value"})
    assert result["result"] == "success"

📚 Usage Examples

Using the Tool Registry

from sap_mcp_server.tools import tool_registry
from sap_mcp_server.protocol.schemas import ToolCallRequest

# List available tools
tools = tool_registry.list_tools()
for tool in tools:
    print(f"- {tool.name}: {tool.description}")

# Call a tool
request = ToolCallRequest(
    name="sap_list_services",
    arguments={}
)
result = await tool_registry.call_tool(request)
print(result)

MCP Client Example

from mcp import StdioServerParameters
from mcp.client.session import ClientSession
from mcp.client.stdio import stdio_client

async def main():
    # Connect to MCP server
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "sap_mcp_server.transports.stdio"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize session
            await session.initialize()

            # Authenticate
            auth_result = await session.call_tool("sap_authenticate", {})

            # Query airlines
            entity_result = await session.call_tool(
                "sap_query",
                {
                    "service": "Z_TRAVEL_RECOMMENDATIONS_SRV",
                    "entity_set": "AirlineSet",
                    "filter": "CARRID eq 'LH'"
                }
            )
            print(entity_result)

Structured Logging

from sap_mcp_server.utils.logger import setup_logging, get_logger

# Production (JSON logs)
setup_logging(level="INFO", json_logs=True)

# Development (colored console)
setup_logging(level="DEBUG", json_logs=False)

# Use logger
logger = get_logger(__name__)
logger.info("Server started", port=8080, transport="stdio")
logger.error("Query failed", error=str(e), query=params)

Input Validation

from sap_mcp_server.utils.validators import (
    validate_odata_filter,
    validate_entity_key,
    sanitize_input
)

# Validate OData filter
if validate_odata_filter("CARRID eq 'LH'"):
    # Safe to execute
    pass

# Sanitize user input
safe_input = sanitize_input(user_data, max_length=1000)

# Validate entity key
if validate_entity_key(key):
    # Fetch entity
    pass

🔒 Security

Defense in Depth

Best Practices

1. Credentials: Store in .env.server, never commit to git
2. SSL/TLS: Always enable in production (SAP_VERIFY_SSL=true)
3. Validation: All inputs validated before SAP calls
4. Logging: Sensitive data excluded from logs
5. Error Handling: Generic error messages to clients

📖 Documentation

📚 Guides

• Configuration Guide: Complete guide for YAML and environment configuration
• Deployment Guide: Production deployment best practices
• Troubleshooting Guide: Common issues and solutions
• OData Service Creation Guide: Step-by-step SFLIGHT OData service creation
• SFLIGHT Demo Guide: Working with SFLIGHT demo scenario

🏗️ Architecture

• Server Architecture: Detailed system architecture and design patterns

📦 Package Documentation

• Server Package README: Server package specific documentation

🌐 Multi-Language Support

• English: Main documentation (this file)
• 日本語 (Japanese): Japanese documentation
• 한국어 (Korean): Korean documentation
• ไทย (Thai): Thai documentation
• 繁體中文 (Traditional Chinese): Traditional Chinese documentation
• 简体中文 (Simplified Chinese): Simplified Chinese documentation
• Español (Spanish): Spanish documentation

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• MCP Protocol: Anthropic's Model Context Protocol
• SAP Gateway: OData v2/v4 integration
• Community: Contributors and testers