# SAP CPI MCP Server

A Python-based MCP server and optional AI agent for connecting to SAP Cloud Integration / SAP CPI.

This project exposes SAP CPI APIs as MCP tools so an MCP-compatible client or AI agent can inspect CPI metadata, runtime artifacts, integration packages, message processing logs, and failed messages.

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Features](#features)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [Environment Variables](#environment-variables)
- [Run the MCP Server](#run-the-mcp-server)
- [Test with MCP Inspector](#test-with-mcp-inspector)
- [Available MCP Tools](#available-mcp-tools)
- [Run the AI Agent](#run-the-ai-agent)
- [Common Commands](#common-commands)
- [Troubleshooting](#troubleshooting)
- [Security Notes](#security-notes)
- [GitHub Setup](#github-setup)
- [License](#license)

## Overview

The server connects to SAP CPI using OAuth client credentials and exposes CPI operations through the Model Context Protocol, or MCP.

An AI client can connect to this MCP server and use the available tools to answer questions such as:

- What are the latest CPI message processing logs?
- Are there any failed messages?
- Which runtime artifacts are deployed?
- What integration packages are available?
- What OData entities are exposed by this CPI tenant?

## Architecture

```text
User / AI Client / MCP Inspector
        |
        | MCP over Streamable HTTP
        v
Python MCP Server
        |
        | HTTPS + OAuth client credentials
        v
SAP Cloud Integration / SAP CPI APIs
```

Optional AI agent flow:

```text
User Question
        |
        v
agent.py
        |
        | LLM tool-calling
        v
MCP Server
        |
        v
SAP CPI APIs
```

## Features

- Python MCP server using `FastMCP`
- Streamable HTTP MCP transport
- SAP CPI OAuth client credentials authentication
- JSON response handling using HTTP `Accept: application/json`
- CPI OData metadata inspection
- CPI message processing log listing
- Failed message search
- Runtime artifact listing
- Integration package listing
- Optional AI agent using OpenRouter
- MCP Inspector support for local testing

## Project Structure

```text
cpi-mcp-server/
├── server.py
├── agent.py
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md
```

## Prerequisites

Install these before running the project:

- Python 3.11 or later
- Node.js LTS, only required for MCP Inspector
- Git
- SAP Integration Suite / SAP CPI tenant
- SAP BTP service key or OAuth client with CPI API access
- Optional OpenRouter API key for the AI agent

## Setup

Clone the repository:

```powershell
git clone https://github.com/jacksnh/CPI-MCP-SERVER.git
cd CPI-MCP-SERVER
```

Create a Python virtual environment:

```powershell
python -m venv .venv
```

Activate the virtual environment on Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks activation, run:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Then activate again:

```powershell
.\.venv\Scripts\Activate.ps1
```

Install dependencies:

```powershell
python -m pip install -r requirements.txt
```

If `requirements.txt` is not available yet, install manually:

```powershell
python -m pip install "mcp[cli]" httpx python-dotenv
```

## Environment Variables

Create a `.env` file in the project root.

You can copy `.env.example`:

```powershell
copy .env.example .env
```

Then edit `.env`:

```powershell
notepad .\.env
```

Example `.env`:

```env
CPI_BASE_URL=https://your-cpi-host
CPI_TOKEN_URL=https://your-token-host/oauth/token
CPI_CLIENT_ID=your-client-id
CPI_CLIENT_SECRET=your-client-secret

OPENROUTER_API_KEY=your-openrouter-api-key
OPENROUTER_MODEL=openai/gpt-4o-mini
MCP_SERVER_URL=http://127.0.0.1:8000/mcp
```

Important: do not commit `.env` to GitHub.

## Run the MCP Server

Start the server:

```powershell
python server.py
```

Expected output:

```text
Starting SAP CPI MCP Server on http://127.0.0.1:8000/mcp
Uvicorn running on http://127.0.0.1:8000
```

Keep this terminal open while using MCP Inspector or the AI agent.

The MCP server URL is:

```text
http://127.0.0.1:8000/mcp
```

## Test with MCP Inspector

Install Node.js LTS if `npx` is not available.

Start MCP Inspector in a second terminal:

```powershell
npx -y @modelcontextprotocol/inspector
```

Open the URL printed by Inspector in the terminal. It usually looks like:

```text
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...
```

Use these settings in MCP Inspector:

```text
Transport Type: Streamable HTTP
URL: http://127.0.0.1:8000/mcp
Connection Type: Via Proxy
```

Click **Connect**.

Start by running the `health_check` tool.

## Available MCP Tools

The server can expose tools such as:

| Tool | Purpose |
| --- | --- |
| `health_check` | Checks whether the MCP server is running. |
| `get_cpi_metadata` | Retrieves CPI OData service metadata. |
| `list_message_processing_logs` | Lists recent CPI message processing logs. |
| `search_failed_messages` | Searches recent failed CPI messages. |
| `get_message_processing_log` | Gets one message processing log by message GUID. |
| `list_integration_runtime_artifacts` | Lists deployed CPI runtime artifacts. |
| `get_integration_runtime_artifact` | Gets one runtime artifact by ID. |
| `list_integration_packages` | Lists CPI integration packages. |

Example tool input for logs:

```json
{
  "top": 5
}
```

## Run the AI Agent

Make sure the MCP server is already running in one terminal:

```powershell
python server.py
```

Open a second terminal and run:

```powershell
python agent.py
```

Example prompts:

```text
Run a health check.
Show me the latest 5 CPI message processing logs and summarize them.
Find the latest 5 failed CPI messages and explain likely root causes.
List deployed CPI runtime artifacts.
```

The agent connects to the MCP server, discovers available tools, calls the relevant tool, and summarizes the result.

## Common Commands

Activate virtual environment:

```powershell
.\.venv\Scripts\Activate.ps1
```

Run MCP server:

```powershell
python server.py
```

Run AI agent:

```powershell
python agent.py
```

Run MCP Inspector:

```powershell
npx -y @modelcontextprotocol/inspector
```

Check if port 8000 is listening:

```powershell
netstat -ano | findstr :8000
```

Check installed Python packages:

```powershell
python -m pip list
```

## Troubleshooting

### `ECONNREFUSED 127.0.0.1:8000`

The MCP server is not running.

Start it in a separate terminal:

```powershell
python server.py
```

Wait for:

```text
Uvicorn running on http://127.0.0.1:8000
```

### `npx is not recognized`

Node.js is not installed or is not on the Windows PATH.

Install Node.js LTS, then reopen VS Code or PowerShell and verify:

```powershell
node -v
npm -v
npx -v
```

### `Not Acceptable: Client must accept text/event-stream`

This is normal if you test `/mcp` with `Invoke-WebRequest` or a browser directly.

The `/mcp` endpoint expects an MCP client, such as MCP Inspector.

### `KeyError: CPI_BASE_URL`

The `.env` file is missing, not saved, or not being loaded.

Check that `.env` is in the same folder as `server.py` and contains:

```env
CPI_BASE_URL=https://your-cpi-host
```

### `501 Not Implemented`

The CPI tenant may not support the endpoint being called, or the endpoint may differ for your tenant type.

Run:

```text
get_cpi_metadata
```

Then check which OData entity sets are available.

### `401 Unauthorized`

Possible causes:

- Wrong `CPI_CLIENT_ID`
- Wrong `CPI_CLIENT_SECRET`
- Wrong `CPI_TOKEN_URL`
- OAuth client does not belong to the CPI tenant

### `403 Forbidden`

The OAuth client exists but does not have the required CPI API roles.

Check SAP BTP role collections and service key permissions.

### `404 Not Found`

Possible causes:

- Wrong `CPI_BASE_URL`
- Wrong CPI region or tenant host
- Endpoint is unavailable in your tenant

## Security Notes

Never commit secrets to GitHub.

Do not commit:

```text
.env
.venv/
```

Recommended `.gitignore`:

```gitignore
.env
.venv/
__pycache__/
*.pyc
node_modules/
.vscode/
.DS_Store
```

If credentials were ever shown in screenshots, logs, chat messages, or committed to GitHub, rotate them immediately.

For production use:

- Use a secret manager instead of `.env`
- Use least-privilege SAP BTP service credentials
- Keep read-only and write-enabled credentials separate
- Add authentication in front of the MCP server
- Avoid exposing the MCP server publicly without access control
- Add audit logging for tool calls

## GitHub Setup

Initialize Git:

```powershell
git init
```

Add remote:

```powershell
git remote add origin https://github.com/jacksnh/CPI-MCP-SERVER.git
```

If remote already exists:

```powershell
git remote set-url origin https://github.com/jacksnh/CPI-MCP-SERVER.git
```

Add files:

```powershell
git add .
```

Commit:

```powershell
git commit -m "Add SAP CPI MCP server and AI agent"
```

Push:

```powershell
git branch -M main
git push -u origin main
```

## License

No license has been added yet. Add a license before sharing or reusing this project publicly.