procurement-mailer-mcp

A Model Context Protocol server that lets an SAP Joule agent read and send email from a scoped Microsoft Exchange mailbox. The agent never talks to Microsoft directly — this server sits in the middle, translating MCP tool calls into Microsoft Graph requests against a single mailbox.

📖 Setup runbook: https://fairconsult-corp.github.io/procurement-mailer-mcp/ 🏛️ Architecture: https://fairconsult-corp.github.io/procurement-mailer-mcp/architecture.html

Architecture

  SAP Joule Agent  ──▶  procurement-mailer-mcp  ──▶  Exchange / MS Graph
   (BTP / Joule)         (this repo, on CF)          (single scoped mailbox)

Invocation flows left-to-right; data flows back right-to-left. Three stages:

Stage	What it does
1 · Joule	Plans the request, picks an MCP tool, calls the server over Streamable HTTP through a BTP destination.
2 · MCP (this repo)	Node.js + TypeScript server on Cloud Foundry. Exposes four tools and maps them onto Graph calls through the graph-mail destination (an Entra app identity).
3 · Graph	Microsoft Graph over Exchange Online, restricted by an application access policy to just the demo mailbox.

Transport

The server is stateless: every POST /mcp builds a fresh McpServer + StreamableHTTPServerTransport pair (sessionIdGenerator: undefined). GET and DELETE on /mcp — the session channels of Streamable HTTP — return 405.

Graph access

There is no MSAL or token juggling in code. @sap-cloud-sdk/http-client's executeHttpRequest resolves the graph-mail BTP destination, performs the OAuth client-credentials exchange, and prefixes /v1.0 on every call. The Entra credentials (tenant ID, client ID, client secret) live in that destination, not in environment variables.

Project layout

src/
├── index.ts          # Express app + Streamable HTTP transport (POST /mcp)
├── server.ts         # Builds the McpServer, registers `ping`, wires in mail tools
├── tools/
│   └── mail.ts       # The three mail tools: list_messages, read_message, send_mail
└── graph/
    └── client.ts     # graphGet / graphPost via the `graph-mail` destination

manifest.yml          # Cloud Foundry app + service bindings (dest, conn, xsuaa)
index.html            # The setup runbook (published to GitHub Pages)
architecture.html     # Architecture page — call flow, components, data model
assets/               # Logo + runbook images

Tools

Tool	Description	Key inputs
ping	Health check — returns pong @ <timestamp>.	note?
list_messages	Recent emails from the mailbox: id, subject, sender, received time, read state.	top (1–25, default 10), unreadOnly
read_message	Full body of one email by id.	messageId
send_mail	Send an email from the mailbox.	to, subject, body, contentType (Text/HTML)

Requirements

• Node.js 22.x (see engines in package.json)
• For deployment: a SAP BTP subaccount with Cloud Foundry, and the graph-mail destination configured (Entra credentials). See the runbook for the full Microsoft-side and BTP setup.

Run locally

npm install

# Dev — tsx watch, hot reload, port 3000 (or $PORT)
npm run dev

# Or build to dist/ and run the compiled server
npm run build
npm start

The server listens on http://localhost:3000/mcp.

Validate with the MCP Inspector

Use a real MCP client — not curl, which can't complete the Streamable HTTP handshake.

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP   URL: http://localhost:3000/mcp
# Connect → List Tools (expect 4) → call `ping` → expect "pong @ <timestamp>"

ping works locally with no extra setup. The three mail tools resolve the graph-mail destination, which only exists on BTP — test those against the deployed route, or feed the SAP Cloud SDK a destinations env var when starting the server locally.

Deploy to Cloud Foundry

The app expects three bound services (see manifest.yml): a destination, connectivity, and xsuaa instance.

cf api <CF_API_ENDPOINT>          # e.g. https://api.cf.us10-001.hana.ondemand.com
cf login --sso
cf target -o "<ORG>" -s <SPACE>

# One-time: create the backing services manifest.yml binds
cf create-service destination lite  procurement-mailer-dest
cf create-service connectivity lite procurement-mailer-conn
cf create-service xsuaa application procurement-mailer-uaa

npm run build
cf push

# After re-binding or changing a service: RESTAGE, never restart
cf restage procurement-mailer-mcp

Restage, never restart. Service bindings are only injected into VCAP_SERVICES on cf restage. cf restart reuses the old droplet and the env stays empty.

Configuration

Setting	Where	Notes
MAILBOX	manifest.yml env / src/graph/client.ts default	The mailbox every call targets.
PORT	injected by Cloud Foundry	Defaults to 3000 locally.
Entra credentials	graph-mail BTP destination	Tenant ID, client ID, client secret — not env vars.

License

ISC