Skip to main content
Glama
abap-adt-mcp-gateway
by lusmjs

abap-adt-mcp-gateway

CI node mcp tools license

An MCP server for SAP ABAP that speaks ADT. One process serves several SAP systems at once, advertises three tools instead of 336, and decides what a call may do from the mode of the system it targets: dev writes, qas reads and tests, prd reads.

It talks to the documented ADT endpoints over HTTPS. No screen scraping, no GUI automation, and nothing on the ABAP side is required unless you want the few surfaces ADT does not expose.

It mounts nothing on its own. If you want an object visible in the editor's own ABAP tree, turn observe on: abap-adt-mcp observe prints the destination folder and the virtual path of each object, and abap-adt-mcp observe --mount writes every configured destination into the editor's workspace file. The tree itself is served by SAP's extension ABAP Development (sapse.adt-vscode); the window reads that file on reload, and the logon inside each tree is manual. A write asks for a tab only when the extension serves abap: and its log says the session is alive, and otherwise the answer carries one observe_note line saying why — see docs/USAGE.md.

Table of Contents

Related MCP server: ABAP-ADT-API MCP-Server

Why this exists

Three problems, one design decision each.

A model cannot hold 336 tool schemas. A client hands the model a bounded list — several stop at 128 — so a 336-entry tools/list ends with a model that believes the tools that did not fit do not exist. This server advertises three tools and keeps the other 336 reachable by name, with their schemas on the server, fetched only when a call needs one.

A developer usually has more than one system. Development, quality and production differ in one way that matters: whether a write is allowed. Each configured system keeps its own ADT session — own cookies, CSRF token, pinned client — alive for the life of the process, and its mode decides what a tool may do there. A refusal says MODE_FORBIDDEN and names the mode that would have accepted it. There is no fourth spelling of mode, and no setting that widens one.

"It worked" is a claim, not a result. ADT answers 2xx for writes that were stored but never activated, for checks that never ran, and for objects that do not exist. Every write tool here reads the active version back and compares it with what it sent; a check that returns no verdict is reported as an error, not as a pass. The known traps are listed per endpoint.

Quick start

Four steps: get the code, write one configuration file, register it with your client, make a call. Nothing here needs SAP access until the last step.

Get the code and build it

git clone https://github.com/rogerix4/abap-adt-mcp-gateway.git
cd abap-adt-mcp-gateway
npm ci
npm run build
node dist/bin.js --coverage

The last line answers 336/336 tools implemented. It needs no configuration and contacts no system — it is the check that the build is intact.

There is no npm package yet, and dist/ is not committed, so npx github:… cannot work: the build has to happen once on your machine. node --version must be 20.11 or newer (see Requirements).

Point it at your systems

Create adt-mcp.config.jsonc in the directory you will start the server from (or pass --config <path>). The smallest file that answers a call is examples/adt-mcp.config.minimal.jsonc:

{
  "$schema": "./adt-mcp.schema.json",
  "systems": [
    {
      "id": "dev",
      "mode": "dev",
      "sid": "DEV",
      "endpoint": { "url": "https://sap.example.com:44300", "client": "100" },
      "auth": { "type": "basic", "username": "env:ADT_USER", "password": "env:ADT_PASSWORD" }
    }
  ]
}

Credentials are references (env:, keychain:, file:), never literals — the client's own configuration never holds a password. Every key, every default and every layer is in docs/CONFIGURATION.md; a file that fails validation says which layer and which key, and the server still starts so you can see that answer.

Register it with your client

The server speaks MCP over stdio. What you write depends on the client, and only the VS Code form was measured here — the six shapes (VS Code, Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI) are in examples/, each as a file you can copy:

{
  "servers": {
    "abap-adt-mcp-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/abap-adt-mcp-gateway/dist/bin.js"]
    }
  }
}

Then restart the client — the server is its child process, so a new build or a new configuration is only picked up when it is started again. The client shows three tools:

GatewayListSystems   which systems exist, their mode, how much of the contract each allows
GatewayListTools     find a tool by group, name pattern, verb or free text
GatewayCallTool      call any tool of the contract by name

Make the first call

GatewayListSystems {}

It answers one line per configured system with its mode and how many of the 336 tools that mode allows, and it contacts nothing. From there the shape is always the same: find a name, ask for its schema, call it.

GatewayListTools  { "group": "ddic" }
GatewayListTools  { "tool": "GetTable", "detail": "schema" }
GatewayCallTool   { "system": "dev", "tool": "GetTable", "arguments": { "table_name": "T000" } }

Diagnostics go to stderr (stdout carries the protocol and nothing else), so a client that shows server logs shows them there. node tools/scripts/mcp-status.mjs prints which servers are running and marks one whose process predates dist/. When a call refuses, read its code and nextAction before retrying — docs/TROUBLESHOOTING.md is organised by that order.

Configure systems

adt-mcp.config.jsonc in the working directory (or next to the package, or at --config <path>). Credentials are references, never literals.

{
  "$schema": "./adt-mcp.schema.json",

  // The process itself.
  "server": {
    "name": "abap-adt-mcp-gateway",
    "logLevel": "info"          // error | warn | info | debug
  },

  // ADT-client integration: `abap-adt-mcp observe`, `GetObjectUri`, and opening the object in
  // the ADT tree after a successful Create / Update. Off by default — with it on, a write also
  // starts the editor CLI.
  "observe": {
    "enabled": false,
    "openAfterWrite": true,     // request the tab after a write, never after Delete
    "codeCli": "code"           // editor CLI to start
  },

  // Used when a call omits `system`; must be one of the ids below.
  "defaultSystem": "dev",

  // Applies to every system.
  "toolPolicy": {
    "timeoutMs": 180000,        // per-request ADT timeout, in milliseconds
    "exclude": []               // names / groups / tags / globs refused everywhere; empty by default
  },

  "systems": [
    {
      "id": "dev",              // also the `system` argument; lowercase, . _ - allowed
      "label": "DEV · client 100",
      "sid": "DEV",             // sy-sysid, three characters — the ADT destination id is built from it
      "mode": "dev",            // dev | qas | prd — the only thing that decides whether a write may happen
      "endpoint": {
        "url": "https://sap.example.com:44300",
        "client": "100",        // three-digit client, "100" or 100
        "language": "EN",       // logon language, default EN
        "systemType": "onprem"  // onprem | cloud, default onprem
      },
      "auth": {
        // "type": "basic" — the only value there is; omit it
        "username": "env:ADT_USER",
        "password": "keychain:abap-adt-mcp-gateway/dev"
      },
      "rfcBackend": "soap",     // soap | odata, default soap — used by the ABAP bridge modules
      "env": {}                 // extra variables handed to the RFC bridge; usually empty
    },
    {
      "id": "prd",
      "label": "PRD · client 100",
      "sid": "PRD",
      "mode": "prd",
      // Narrowing only: naming a write tool here does not make it allowed on a prd system.
      "include": ["Get*", "ddic"],
      "endpoint": { "url": "https://sap.example.com:44300", "client": "100" },
      "auth": {
        "username": "env:ADT_USER_PRD",
        "password": "keychain:abap-adt-mcp-gateway/prd"
      }
    }
  ]
}

Only systems[].id is required. Everything else is either a default (shown above: logLevel info, observe off, timeout 180 s, language EN, systemType onprem, rfcBackend soap) or something you have to supply to connect at all (endpoint.url, auth.username, auth.password). A system without mode counts as prd.

env: needs the variable set; keychain: needs an entry you create once. The three commands, one per platform:

# Windows
cmdkey /add:abap-adt-mcp-gateway/dev /user:ADT_USER /pass

# macOS
security add-generic-password -s abap-adt-mcp-gateway -a dev -w

# Linux (libsecret)
secret-tool store --label="abap-adt-mcp-gateway dev" service abap-adt-mcp-gateway account dev

Start with env: if you only want the first call to work; move to keychain: before the credential ends up in your shell history. The full key list is in docs/CONFIGURATION.md; unknown keys are an error, not a no-op.

How a call works

client ──stdio──▶ GatewayListTools { group: "ddic" }        → names, one line each
               ──▶ GatewayListTools { tool: "CreateTable", detail: "schema" }  → its JSON Schema
               ──▶ GatewayCallTool { tool: "CreateTable", arguments: {…}, system: "dev" }

The tool argument of GatewayCallTool carries an enum of every name the configured systems allow, so a model sees the whole contract without receiving 336 schemas. If the arguments do not match, the answer contains the schema instead of only an error.

What a name may do is decided per call from the target system's mode, and refused with MODE_FORBIDDEN, naming the mode that would have accepted it. A name the contract does not have answers UNKNOWN_TOOL — the two mistakes stay distinguishable.

What each mode allows

mode

actions

typical use

dev

read, data, diag, test, check, write, activate, lock, transport

development client, writable

qas

read, data, diag, test, check

quality client, nothing is written

prd

read, data, diag

production, read only

How much of the contract each mode reaches:

mode

tools allowed

of 336

dev

336

everything

qas

146

reads, checks, data, diagnostics, unit tests

prd

108

reads, data, diagnostics

A system without mode is treated as prd. Exactly these three values exist — there is no fourth spelling, because this setting decides whether a production system can be written to. include narrows the set for one system (group, tag, tool name or glob); exclude removes last and wins. Neither can widen a mode.

Per-group counts, and what each mode allows in one group:

node tools/scripts/tool-presets.mjs

The contract

336 tools in twelve groups. A group is the one home of a tool, in the listing and in the generated reference, so a name is never described two ways.

Group

Tools

What it reaches

object-core

97

programs, classes, interfaces, packages, includes, where-used, search, object structure

cds-rap

61

CDS views, metadata extensions, behavior definitions and implementations, service definitions and bindings

ddic

54

domains, data elements, tables, structures, with their check and activation

ui

31

screens, GUI statuses, text pools

functions

25

function groups and function modules

testing

25

ABAP Unit runs and test includes, CDS unit tests

runtime-diag

17

dumps, feeds, system messages, profiler traces

analysis

11

type information, enhancement spots and implementations, usage snippets, batch-job and transaction usage

transport

5

requests and tasks

forms

5

SmartForms: content, layout, render to PDF

data

2

table contents and ad-hoc SQL

session-admin

2

session state and profile reload

Every tool, its group and its full argument schema are in docs/TOOLS.md, generated from tools/catalog.json; npm run verify fails when the two drift apart.

Low in a name means "the caller owns the lock and the session": one tool call, one ADT request. It is not simply the twin of the tool next to it — 89 of the 134 *Low tools have no high-level sibling, and the ones that do differ in their arguments, not only in their level.

Tested against

The table below lists what was exercised and where.

What

Where it was verified

ADT resources, activation, locks, transports, CDS and RAP

an S/4HANA development client, logon language ZH

The ABAP bridge modules (abap/)

an ECC system on BASIS 7.54 — the sources are written for that release and encode JSON through ZCL_JSON, because /ui2/cl_json is missing there

Every tool in the contract

a live sweep on a development client: 336 of 336 called, in $TMP, cleaned up afterwards — see docs/LIVE-TESTING.md

The offline suite

467 tests over 39 files, no network: a scripted HTTP layer and InMemoryTransport

SAP releases differ in small, load-bearing ways: which media type an endpoint accepts, whether a syntax check reads the payload you hand it, whether a resource exists at all. Where a difference was found, the code decides at runtime and docs/TROUBLESHOOTING.md records what SAP answered. If your release behaves differently, that is a bug report worth sending: include the status, the root element and the SAP text.

Requirements

  • Node 20.11 or newer. npm ci && npm run build is the whole toolchain.

  • HTTPS access to /sap/bc/adt on the target systems, and a user with S_DEVELOP.

  • Optional: the ABAP modules in abap/README.md for screens, GUI statuses, text elements and SmartForms — the four surfaces ADT does not expose.

  • Optional: @napi-rs/keyring (an optional dependency) for keychain: credentials.

What it does not do

  • No HTTP transport. stdio only.

  • No GUI, screen, or transaction automation: it drives documented ADT resources, plus the seven bridge modules in abap/ for the four surfaces that have no ADT resource.

  • Writes only on mode: "dev". Nothing in this project will make a qas or prd system accept a write, and a refusal is a refusal, not a retry hint.

  • No BTP ABAP environment support for the RFC-based parts: there is no /sap/bc/soap/rfc there.

  • No logon on your behalf. The abap: tree's session belongs to SAP's extension; the gateway reads that extension's own log to know whether a tab is worth asking for, and says so in observe_note when it is not. See troubleshooting.

  • No source cache, no version history, no interactive debugger — see what has no channel.

Documentation

Start with the map: docs/README.md. Behind it:

Question

File

The fastest path from a clone to a first call

examples/

How to drive a tool correctly: payloads, activation, locks, the traps

docs/USAGE.md

Every configuration key, and where the file is looked for

docs/CONFIGURATION.md

Sessions, locks, concurrency, the write boundary, why the shape is this shape

docs/ARCHITECTURE.md

Symptom to cause to fix

docs/TROUBLESHOOTING.md

Every tool, its group and its arguments (generated)

docs/TOOLS.md

How the live sweep works, and what the last one found

docs/LIVE-TESTING.md

The ABAP bridge modules

abap/README.md

Working on this repository, with or without an AI agent

AGENTS.md

Changes per release

CHANGELOG.md

Reporting a vulnerability

SECURITY.md

Sending a change

CONTRIBUTING.md

Where to ask a question

SUPPORT.md

How we treat each other

CODE_OF_CONDUCT.md

npm run verify runs the whole gate: catalog consistency, the private-data scan, types for src and tests, the generated schema and tool reference, documentation style and links, the coverage count and the test suite. It runs on every push in .github/workflows/ci.yml, on Node 20 and 22, Linux and Windows.

Project status

1.0.0 — first public release. The tool contract is frozen: a capability that is missing becomes a new tool in a minor release, and a released name never changes meaning or shape.

Known gaps are stated, not half-implemented. UpdateUnitTest and DeleteUnitTest answer NOT_IMPLEMENTED because ADT has no verb for them — measured: PUT and DELETE on /abapunit/runs/<id> answer 405, and GET answers 406. The five Validate* verbs that check a name that already exists answer "already exists", which is the correct verdict and not a defect.

Deliberately not planned: GUI automation, a second transport, a plugin system, and any setting that could widen a mode.

Contributing

Small, focused pull requests are easier to review than large ones, and a bug report carrying the SAP text and the status is worth more than a fix that guesses. Rules to know before you start: CONTRIBUTING.md — and for anything beyond a typo, AGENTS.md, the same file an AI agent working here reads.

License

Apache License 2.0: use it, fork it, change it, ship it, sell it. The licence asks for two things and nothing else — keep the copyright and licence notices, and read the patent and warranty clauses before you rely on it. Third-party notices are reproduced in NOTICE.

Apache-2.0 is OSI-approved, so GitHub labels this repository "Apache License 2.0"; LICENSE is the whole text and there is nothing to accept before you read the source.

Available Tools

3 tools
GatewayCallToolA

Call any tool of the contract by name. Arguments are the tool's own arguments; system selects the SAP system. Not every name is allowed on every system — a refusal names the mode and the mode that would accept it. If the arguments do not match the tool's schema, the answer carries the schema, not only an error.

Inputs: tool (required), system, arguments.

GatewayListSystemsA
Read-onlyIdempotent

List the configured SAP systems with their mode. Available: (none configured). A "dev" system accepts writes, a "qas" system reads, tests and checks, a "prd" system reads only — which tool may run where is decided per call and reported as MODE_FORBIDDEN.

Inputs: no named parameters.

GatewayListToolsA
Read-onlyIdempotent

Search the contract (336 tools) by group, name pattern, verb or free text. These three gateway tools are the only ones advertised, so this is how a tool is discovered: find it here, then call it with GatewayCallTool. detail: "names" (default), "descriptions" (adds group and effect) or "schema" (the full input schema of one tool).

Inputs: tool, verb, group, limit, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct stage of the workflow: discover systems, discover tools, invoke a tool. There is no plausible way to confuse listing systems with searching the contract or calling a tool, and the descriptions reinforce the boundary (find it here, then call it with GatewayCallTool).

    Naming Consistency5/5

    All three follow the same predictable Gateway+Verb+Noun pattern (GatewayListSystems, GatewayListTools, GatewayCallTool) with identical PascalCase and prefixing. The shared 'Gateway' prefix also clearly signals these are meta-tools rather than contract tools.

    Tool Count5/5

    A gateway exposing a 336-tool contract should have a minimal meta-surface, and three tools covers discovery, invocation and context. Each tool earns its place; adding more would bloat the advertised surface and defeat the gateway's purpose.

    Completeness4/5

    The lifecycle is closed: list systems, search the contract by group/name/verb/text, then call with schema-on-mismatch error recovery. Minor gaps exist — there is no way to pre-check whether a tool is permitted on a given system without attempting the call, and no dedicated schema/introspection tool separate from the search detail flag.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      Not graded
      maintenance
      An MCP server that facilitates seamless interaction with SAP ABAP systems to manage development objects, transport requests, and source code. It provides a comprehensive suite of tools for performing syntax checks, object searches, and code modifications via the ADT API.
      100
      -
    • A
      license
      C
      quality
      D
      maintenance
      An MCP server that enables seamless communication between ABAP systems and MCP clients using the ABAP Development Tools (ADT) API. It provides tools for managing ABAP objects, handling transport requests, and performing code analysis directly through MCP-compatible interfaces.
      100
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Multi-system MCP server for reading and writing ABAP source via SAP ADT, with write safety controls and a local web admin.
      2
      -