Skip to content

Setup

Jump to bottom
stud0709 edited this page Aug 2, 2026 · 13 revisions

Setup

A Note on Updates

The Dashboard Web UI now includes an automated Upgrade Assistant that checks database schema version state, lists applied/pending incremental schema upgrades, and offers a fresh database reinstallation path (which recreates the database schemas while preserving connection credentials in .sap_credentials.json).

0. Prerequisites

  • Node.js (https://nodejs.org)
  • AI IDE with MCP support
  • SAP system to connect to
  • Windows 10+ x64 / - linux/amd64 (expected to work on modern glibc-based distributions as Ubuntu 22.04+, Debian 12+, RHEL...)

1. Registering the Bridge

Note: Every AI IDE slightly differs in how it handles MCP server and skill registration. Read the documentation of your AI IDE or ask your AI agent to help you with the registration process.

The sap-bridge operates as an orchestrator-agnostic MCP server, running as a persistent background HTTP/SSE daemon. This ensures the database, decrypted vault, and Object Guard approvals remain active in memory and are not killed by the IDE's task-cleanup processes.

Starting the Daemon

Before launching your AI IDE, start the server using the provided helper scripts located in your skill's references/ subfolder:

  • Windows: Run references/start-server.cmd
  • macOS / Linux: Run references/start-server.sh

By default, the server binds to loopback (127.0.0.1) on port 58454.

Client Configuration

Since most local MCP clients (such as Codex Desktop, Claude Desktop, Cursor, and Antigravity) only support local stdio processes, you use the standard mcp-remote proxy bridge. It translates local Stdio pipes into network calls to the persistent SSE server, automatically handling HTTP-first fallback.

1. In JSON config files (e.g., Claude Desktop, Cursor, Antigravity)

Add this to your mcpServers settings block:

{
  "mcpServers": {
    "sap-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:58454/mcp"
      ]
    }
  }
}

2. In TOML config files (e.g., Codex config.toml)

Add this to your .codex/config.toml:

[mcp_servers.sap-dev]
command = "npx"
args = ["-y", "mcp-remote@latest", "http://127.0.0.1:58454/mcp"]

2. Setting Up Workspace

Copy the sap-dev skill folder into your workspace folder (or into a global skill storage). In the workspace, it's typically .agents/skills/. The global skill storage is IDE dependent.

Another way to use the skill documents across multiple folders is a symbolic link.

  • on Windows (in Admin mode):
New-Item -ItemType SymbolicLink -Path "<your_workspace>\.agents\skills\sap-dev" -Value "<reference_location_of_the_skill>\sap-dev"
  • on Linux and Mac:
ln -s "<reference_location_of_the_skill>\sap-dev" "<your_workspace>\.agents\skills\sap-dev"

3. Setting Up Credentials

  1. Ask your AI Agent for the Dashboard URL (the agent will run the sap_bridge_status MCP tool and provide you with the complete, clickable link containing your workspace's unique ID).
  2. Open that URL in your standard Web Browser.
  3. If this is your first time securely booting the Bridge, the Dashboard will check the prerequisites and automatically prompt you to establish your Master Password. This will generate .sap_credentials.json at the root of your workspace folder. The credentials, master password hash, and vault state are completely isolated per workspace context.
  4. Once your Web UI encryption is initialized, you can add SAP system connections.

Connection Tile

  • You can toggle system visibility (to the agent) and writability on the fly.
  • You can group connections using the Landscape text attribute (e.g. "Company 1"). When creating or editing connections, the Web UI provides an autocomplete dropdown listing existing landscapes to prevent typos.
  • Fail-Safe Restrictions: Pushing changes and activating objects are strictly blocked on systems marked with a "quality", "production", or "test" role. If a Q, P, or Test system belongs to a landscape, the error message will automatically search the workspace vault and suggest using the corresponding "development" system in the same landscape.
  • Additional controls will be shown depending on the chosen connection type and whether the password should be injected at runtime.

4. Setting Up RPC Proxy (Optional)

Some tools (like sap_read_screen) cannot reuse an existing ADT endpoint and rely on ABAP logic. To make them work, you must deploy the ABAP RPC proxy components to your SAP system and configure an ICF node.

  1. Deploy Proxy Components:
    • Open the SAP-Bridge Web Dashboard and click the Upgrade tab in the sidebar.
    • Select your target SAP system from the dropdown and click Check Status.
    • Check the boxes for the core RPC interface/classes:
      • zcl_sap_dev_object_hdlr.clas.abap (Unified Abstract Object Handler Base Class)
      • zcl_sap_dev_rpc.clas.abap (and its .locals_def/.locals_imp includes)
      • zcl_sap_dev_rpc_ext.clas.abap (and its .locals_def/.locals_imp includes)
      • zcl_sap_dev_dev_helper.clas.abap (Development-Only Write Operation Helper Class)
    • Environment Packaging & Transport Rules:
      • For Development (D) System: Deploy all components. You can choose to deploy them to a local package ($TMP) or a transportable package.
      • For Quality (Q) & Production (P) Systems: To comply with security audits and avoid ABAP Test Cockpit (ATC) check errors (which flag dynamic writing statements such as INSERT TEXTPOOL), split the components:
        1. Transport only the safe, read-only classes (ZCL_SAP_DEV_RPC, ZCL_SAP_DEV_RPC_EXT, ZCL_SAP_DEV_OBJECT_HDLR, and ZCL_SAP_DEV_TUNNEL) along with the ICF Node to the Q and P systems.
        2. Assign the development-only writing helper class ZCL_SAP_DEV_DEV_HELPER to a local package (like $TMP) strictly in the D-system. It should be excluded from any transport requests. This turns off writing capabilities when the proxy runs in Q and P environments.
    • Under Deployment Settings, specify the target package. If deploying to a transportable package in D, enter a valid Transport Request (Task) number.
    • Click Deploy & Activate Selected. The assistant will automatically create, lock, upload, and activate the objects on the backend in the correct dependency order.
  2. Create ICF Node:
    • Open SAP GUI and run transaction SICF.
    • Navigate to /default_host/sap/bc.
    • Create a new sub-element named zsapdevrpc (or any custom path).
    • In the Handler List tab, enter the extension class ZCL_SAP_DEV_RPC_EXT (which inherits from ZCL_SAP_DEV_RPC and allows subclassing custom translation handlers).
    • Save and Activate the ICF node.
  3. Enable in Dashboard: The daemon automatically probes the availability of the RPC proxy node on startup. If you configured a custom ICF path on your SAP system (other than /sap/bc/zsapdevrpc), open the SAP-Bridge Web Dashboard, edit your connection, click the Agent Settings icon (file with a gear), and specify your custom path in the Agent RPC Path field.

Agent Settings

5. Setting Up WebGUI Deep Linking (Optional)

To enable deep-linking to specific line numbers and subroutines directly from the ATC Findings table in the Web UI to the SAP WebGUI, you must deploy a custom helper program and transaction code:

  1. Deploy Navigation Program: In the Web Dashboard's Upgrade tab, check the box for z_navigate_to_line.prog.abap, configure target package details, and click Deploy & Activate Selected (or manually upload the code from references/z_navigate_to_line.prog.abap in your IDE).
  2. Create Transaction Code: Create a transaction code named exactly Z_SAP_DEV_NAV in SE93.
    • Choose Program and selection screen (report transaction).
    • Enter your deployed program name (e.g. Z_NAVIGATE_TO_LINE) and selection screen 1000.
    • Under GUI Support, check SAP GUI for HTML (WebGUI) and save.
  3. Automatic Detection: The Web UI dynamically checks if transaction Z_SAP_DEV_NAV is registered on the SAP backend. If available, the screen-share deep-linking buttons will automatically appear next to your ATC findings in the Actions column. No manual dashboard configuration is required.

Troubleshooting

"An attempt was made to access a socket in a way forbidden by its access permissions" (Windows)

On Windows machines running Hyper-V or WSL2, the host networking driver (WinNAT) dynamically reserves TCP port ranges. If port 58454 falls inside one of these dynamically reserved exclusion ranges, the sap-bridge daemon will fail to bind to it and fall back to a random port.

How to resolve this:

Run the following commands in an Administrator PowerShell session:

  1. Stop the network translation service: 
    net stop winnat
  2. Reserve port 58454 persistently so WinNAT does not dynamically allocate it in the future: 
    netsh int ipv4 add excludedportrange protocol=tcp startport=58454 numberofports=1
  3. Restart the network translation service: 
    net start winnat
  4. Restart the sap-bridge daemon. It will now successfully bind to port 58454.

Clone this wiki locally