Wiring Microsoft Exchange to a Joule procurement agent over MCP

The agent never talks to Microsoft directly. A custom MCP server sits in the middle: Joule issues a tool call, the server translates it into a Microsoft Graph request against a single scoped mailbox, and hands the result back. Three stages, two directions — invocation flows left-to-right, data flows back right-to-left.

The companion architecture page covers the same three stages visually — the runtime call flow, the component architecture, and the procurement data model — and is worth keeping open alongside this runbook.

Access & accounts

Local tooling

Same toolchain on both platforms — Node (via nvm), the Cloud Foundry CLI with the MultiApps plugin, the MTA build tool, and the Microsoft-side config tooling (Azure CLI + PowerShell with the Exchange Online module). Pick the block for your OS.

macOS (Apple Silicon)

# Homebrew, if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node via nvm (LTS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts && nvm use --lts

# Cloud Foundry CLI v8 + MultiApps (MTA) plugin + MTA build tool
brew install cloudfoundry/tap/cf-cli@8
cf install-plugin multiapps
npm install -g mbt

# Microsoft-side config tooling
brew install azure-cli
brew install --cask powershell
pwsh -c "Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force"

# Remove the broken x86_64 install
cf uninstall-plugin multiapps

# Download the arm64 build from GitHub and install it manually
curl -LO https://github.com/cloudfoundry/multiapps-cli-plugin/releases/latest/download/multiapps-plugin.osxarm64
chmod +x multiapps-plugin.osxarm64
cf install-plugin ./multiapps-plugin.osxarm64 -f

# Verify
cf plugins | grep -i multiapps

Linux alternative (Debian / Ubuntu)

# Node via nvm (LTS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts && nvm use --lts

# Cloud Foundry CLI v8 (official apt repo) + MultiApps plugin + MTA build tool
wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo gpg --dearmor -o /usr/share/keyrings/cf-cli.gpg
echo "deb [signed-by=/usr/share/keyrings/cf-cli.gpg] https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
sudo apt update && sudo apt install -y cf8-cli
cf install-plugin multiapps
npm install -g mbt

# Microsoft-side config tooling
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# PowerShell (Microsoft apt repo — adjust the Ubuntu version to match `lsb_release -rs`)
wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
sudo dpkg -i packages-microsoft-prod.deb && rm packages-microsoft-prod.deb
sudo apt update && sudo apt install -y powershell
pwsh -c "Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force"

This stage produces the three values the integration authenticates with — tenant ID, client ID, client secret — which land in the graph-mail destination in Stage 04, and locks the app down to a single mailbox. Do it first: nothing downstream works without these values.

1 · Register the app & grant Graph permissions

1. In the Entra admin center → App registrations → New registration. Single tenant is fine for a demo.
2. On the new app's Overview page, copy the Application (client) ID and the Directory (tenant) ID — these are the CLIENT_ID and TENANT_ID used in the access policy below and in the graph-mail destination (Stage 04).
3. Under API permissions, add Microsoft Graph → Application permissions → Mail.Read and Mail.Send.
4. Click Grant admin consent — the status column must read Granted for both.
5. Under Certificates & secrets, create a client secret and copy the value immediately (it's shown once).

2 · Scope the app to one mailbox (Exchange Online)

By default a Graph app with Mail.Read can read every mailbox in the tenant. An application access policy restricts it to the demo mailbox only.

If the demo mailbox doesn't exist yet, create it first: Exchange admin center → Recipients → Mailboxes → Add a shared mailbox (no license needed, covered by Exchange Administrator), or a licensed user in the Microsoft 365 admin center (needs User Administrator + a mailbox license). Its primary address — here procurement-agent@FairConsultCorp.onmicrosoft.com — is the <MAILBOX_UPN> below and the MAILBOX value in manifest.yml (Stage 03).

Everything below runs in PowerShell, not bash. PowerShell itself was installed in Stage 01 (brew install --cask powershell on macOS, apt install powershell on Linux) — drop into a session from your terminal first:

# Launch a PowerShell session — your prompt changes to `PS >`
pwsh

# First time only: install and load the Exchange Online module
Install-Module ExchangeOnlineManagement -Scope CurrentUser -Force
Import-Module ExchangeOnlineManagement

# Sanity check — should print the module with its version
Get-Module ExchangeOnlineManagement

# (When you're done later, `exit` drops you back to bash)

With the module loaded, connect and create the policy:

Connect-ExchangeOnline

# A security group holding the mailbox(es) the app may touch
New-DistributionGroup -Name "MCP-Scoped-Mailboxes" -Type Security
Add-DistributionGroupMember -Identity "MCP-Scoped-Mailboxes" -Member <MAILBOX_UPN>

# Restrict the app to that group only
New-ApplicationAccessPolicy `
  -AppId <CLIENT_ID> `
  -PolicyScopeGroupId "MCP-Scoped-Mailboxes" `
  -AccessRight RestrictAccess `
  -Description "Restrict procurement-mailer-mcp to the demo mailbox"

# Confirm: Accessible = should be True for the scoped mailbox, denied elsewhere
Test-ApplicationAccessPolicy -Identity <MAILBOX_UPN> -AppId <CLIENT_ID>

Runtime & dependencies

Configuration

The Entra credentials from Stage 02 are not environment variables. The server reaches Graph through the graph-mail BTP destination (Stage 04), resolved at runtime via the bound destination service. The app's own config is just the mailbox — PORT is injected by Cloud Foundry — and lives in manifest.yml:

applications:
  - name: procurement-mailer-mcp
    memory: 256M
    disk_quota: 512M
    buildpacks:
      - nodejs_buildpack
    command: npm start
    services:
      - procurement-mailer-dest
      - procurement-mailer-conn
      - procurement-mailer-uaa
    env:
      MAILBOX: procurement-agent@FairConsultCorp.onmicrosoft.com

Transport shape

The server is stateless: every POST /mcp builds a fresh server + transport pair (sessionIdGenerator: undefined), and GET/DELETE — the session channels of Streamable HTTP — answer 405. Keep the route exactly /mcp; the Joule-side destination is configured without it (see Stage 04).

import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { buildServer } from "./server.js";

const PORT = Number(process.env.PORT ?? 3000);

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // stateless
  });
  res.on("close", () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

// Stateless mode: no GET/DELETE session handling.
app.get("/mcp", (_req, res) => res.status(405).send("Method Not Allowed"));
app.delete("/mcp", (_req, res) => res.status(405).send("Method Not Allowed"));

app.listen(PORT, () => {
  console.log(`MCP server on http://localhost:${PORT}/mcp`);
});

Graph access

No MSAL and no token juggling in code — executeHttpRequest resolves the graph-mail destination, handles the OAuth client-credentials exchange, and prefixes /v1.0:

import { executeHttpRequest } from "@sap-cloud-sdk/http-client";

const DESTINATION = { destinationName: "graph-mail" };

// The shared mailbox every call targets. Overridable via env for other demos.
export const MAILBOX =
  process.env.MAILBOX ?? "procurement-agent@FairConsultCorp.onmicrosoft.com";

export async function graphGet(path: string): Promise<any> {
  const res = await executeHttpRequest(DESTINATION, {
    method: "get",
    url: `/v1.0${path}`,
  });
  return res.data;
}

export async function graphPost(path: string, body: unknown): Promise<number> {
  const res = await executeHttpRequest(DESTINATION, {
    method: "post",
    url: `/v1.0${path}`,
    data: body,
  });
  return res.status; // sendMail returns 202 with no body
}

Deploy to Cloud Foundry

# Copy the exact API endpoint from BTP cockpit → Cloud Foundry Environment
cf api <CF_API_ENDPOINT>   # e.g. https://api.cf.us10-001.hana.ondemand.com
cf login --sso
cf target -o "Fairconsult Corp.-demo" -s procurement-demo

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

# Build, then push — manifest.yml binds the services and sets MAILBOX
npm run build
cf push

# If you re-bind or change a service later: RESTAGE, never restart
cf restage procurement-mailer-mcp

Two destinations live in the BTP subaccount → Connectivity → Destinations: one the MCP server uses to call Microsoft Graph, and one Joule Studio uses to reach the MCP server.

1 · graph-mail — MCP server → Microsoft Graph

This is where the three values from Stage 02 live — src/graph/client.ts resolves this destination by name through the bound destination service, and the SAP Cloud SDK handles the token exchange.

2 · Joule Studio → MCP server

1. In SAP Build Control Tower → Destinations, register the Joule-side destination from Stage 04. The subaccount destination alone is not enough — the MCP server only becomes available in Joule Studio after this step.
2. In Joule Studio, add the MCP server as a tool source, pointing at that destination.
3. Create the agent (expertise + instructions below) and attach the MCP tool source to it — without the attachment the agent never sees the four tools.
4. Build the capability (e.g. Procurement-Replica) that surfaces the tools, and version it.
5. Deploy per member in the shared Control Tower environment (ProcurementServiceEnv) — only needed when publishing; see the note below.

Agent configuration (example)

The wording is up to you — this is the configuration used for this demo. The one hard requirement: attach the MCP tool source to the agent, or none of the four tools are callable.

That's the whole setup. From here you just test the agent: open it in Joule Studio and prompt it in plain language — "check the procurement inbox" or "email finance confirming the integration works." The agent picks the right MCP tool on its own and calls this server, which runs the Graph request against the mailbox and hands the result back. No manual tool wiring per request — the agent calls the MCP automatically whenever you ask it to send or read email.

Two rounds: first locally with npm run dev and the MCP Inspector, then against the deployed route. In both cases validate with a real MCP client — not raw curl, which can't complete the Streamable HTTP handshake and will mislead you.

Round 1 · Local — npm run dev + MCP Inspector

# Terminal 1 — run the server locally (tsx watch, port 3000)
npm run dev

# Terminal 2 — MCP Inspector, a point-and-click MCP client (opens in the browser)
npx @modelcontextprotocol/inspector

# In the Inspector UI:
#   Transport: Streamable HTTP  ·  URL: http://localhost:3000/mcp
#   Connect → List Tools (expect 4) → call ping → expect "pong @ <timestamp>"

Round 2 · Deployed — same Inspector, deployed route

No script needed — in the Inspector from Round 1, swap the localhost URL for the deployed route https://procurement-mailer-mcp.cfapps.us10-001.hana.ondemand.com/mcp. Hit Connect, then List Tools: all four methods from src/server.ts / src/tools/mail.ts should appear, which proves the deployed version is connected to the MCP endpoint. Calling ping and list_messages from here also exercises the full Graph chain against the live mailbox.

# The deployed URL is the app's route on Cloud Foundry
cf app procurement-mailer-mcp
#   ...
#   routes:   procurement-mailer-mcp.cfapps.us10-001.hana.ondemand.com

# Prefix https:// and append /mcp for the Inspector's URL field:
#   https://procurement-mailer-mcp.cfapps.us10-001.hana.ondemand.com/mcp

# No CLI handy? BTP cockpit → subaccount → Cloud Foundry → Spaces →
#   procurement-demo → procurement-mailer-mcp → Application Routes

end of runbook · setup order Graph → MCP → Joule · back to top ↑