SAP BTP · Model Context Protocol

Architecture of the procurement mailer integration

SAP Joule Agent → procurement-mailer-mcp → Exchange / MS Graph

How the pieces fit together — the runtime call path an email prompt takes, the component makeup of the caller / bridge / data-source, and the procurement data domain the agent reasons over. The companion setup runbook covers how to build each stage.

← Back to the setup runbook

Framing

Two planes

The solution splits cleanly into two planes. The call plane is the request/response path — a user prompt travels through Joule, into this MCP server, out to Microsoft Graph, and back as a rendered answer. The data plane is the procurement domain the agent operates against: products, stock levels, purchase orders, allocations. This server is the bridge between the two — it turns an agent's intent into a concrete mailbox action.

These diagrams are native recreationsEverything below is drawn in HTML/CSS/SVG — no image files — so it stays crisp at any zoom and matches the runbook's theme. The sections map to the three source diagrams: runtime call flow, setup & architecture, and the procurement apps schema.

The call plane · runtime

Runtime call flow

One email prompt, nine steps. Invocation runs left-to-right; data flows back right-to-left as dashed returns. The MCP server holds no session — every call rebuilds a fresh server + transport pair.

Steps 4–5 are the OAuth2 client-credentials handshake the SAP Cloud SDK performs transparently; steps 6–7 are the actual Graph call. The server never stores a token — the graph-mail destination handles it per request.

The call plane · static view

Component architecture

The same three stages, decomposed into the parts you configure. The caller and data source are configuration on either side; the bridge in the middle is this repository.

1 · SAP Joule Agent
caller

BTP destination — route URL WITHOUT a trailing /mcp

Destination property sap-joule-studio-mcp-server = true

Joule Studio — MCP registered as a tool source

Capability bound to skill · per-member deploy in Control Tower env

Runtime: user prompt → plan intent → select MCP tool

2 · procurement-mailer-mcp
bridge · this repo

Node.js + TypeScript · @modelcontextprotocol/sdk

SAP Cloud SDK — BTP service access

Streamable HTTP transport exposed at /mcp

Tools: ping · list_messages · read_message · send_mail

Cloud Foundry · procurement-demo space · us10 region

3 service bindings rebound + restaged → VCAP_SERVICES

Entra app creds: client ID · tenant ID · client secret

3 · Microsoft Exchange / Graph
data source

Entra ID app registration (client ID, tenant ID, secret)

Graph app permissions: Mail.Read · Mail.Send + admin consent

Exchange Online app access policy → scope to demo mailbox

OAuth2 client-credentials → token endpoint → access token

Graph endpoints: list messages / read message / sendMail

→ call path 1 · tool call /mcp · 2 · OAuth2 token + Graph API
← return path 3 · mail data / result · 4 · tool result → render

The data plane · domain

Procurement data model

The domain the Joule agent reasons over — the CAP backend behind the procurement service. PK marks a primary key, FK a foreign key. Product and Location are the hubs almost everything else references.

ProcurementRequest

request_idPK	int
requested_qty	int
status	varchar
raised_by	varchar
created_at	datetime
product_idFK	int
location_idFK	int

Product

product_idPK	int
name	varchar
category	varchar
safety_stock_level	double
current_stock_level	double

StockLevel

stock_level_idPK	int
quantityOnHand	int
reorderPoint	int
safetyStock	int
location_idFK	int
product_idFK	int

Location

location_idPK	int
name	varchar
type	enum
city	varchar

PurchaseOrder

po_idPK	int
po_number	varchar
status	varchar
expected_delivery_date	datetime
received_date	datetime
disruption_reason	enum
product_quantity	int
po_total	double
allocation_idFK	int
product_idFK	int
shipToLocation_idFK	int

ProcurementIssue

issue_idPK	int
status	varchar
description	text
created_at	datetime
resolved_by	varchar
notes	text
purchase_order_idFK	int

AllocationResult

allocation_idPK	int
allocated_quantity	int
total_effective_cost	double
rationale_summary	text
created_at	datetime
suggested_by_agent	boolean
product_idFK	int
location_idFK	int

⋔ crow's foot = many · │ bar = one · each line runs parent → child along the FK

Relationships

Product 1 — ∗ StockLevel · ProcurementRequest · PurchaseOrder · AllocationResult (via product_id)
Location 1 — ∗ StockLevel · ProcurementRequest · AllocationResult, and PurchaseOrder (via shipToLocation_id)
AllocationResult 1 — ∗ PurchaseOrder (a costed allocation drives one or more purchase orders)
PurchaseOrder 1 — ∗ ProcurementIssue (disruptions logged against an order)

The mailer MCP server doesn't read these tables directly — this is the business context the agent works in. When the agent sends or reads mail about a purchase order or a stock shortfall, these are the entities it's reasoning about.