Turning SAP CAP Services into MCP Servers with @cap-js/mcp: A Practitioner's Guide (2026)
For CAP developers, BTP architects and partners who want AI agents to use their custom business services — safely, with the CAP security model intact.
The Model Context Protocol (MCP) has become the standard way for AI agents to discover and call tools. SAP's CAP team embraced it in the June 2026 CAP release with a new MCP protocol adapter (Beta). From a CAP developer's point of view, MCP is now "just another protocol" — exactly like OData, REST, GraphQL or HCQL.
This guide explains what the adapter does, how to use it correctly, and the design decisions that separate a demo from a production-grade agent tool.
1. Two different "CAP MCP" packages — don't mix them up
@cap-js/mcp — the runtime adapter. Exposes your CAP application services to AI agents at runtime (e.g., an agent asks "list all overstocked products").
@cap-js/mcp-server — a developer tool (command cds-mcp) that helps coding assistants build CAP projects, with tools such as model search and CAP documentation search.
Mixing these up is the most common mistake we see in partner proposals. One serves end-user agents in production; the other serves developers in their IDE.
2. Getting started (Node.js)
Add the plugin to your CAP project:
npm add @cap-js/mcpAnnotate the service you want to expose:
// srv/annotations.cds
using { CatalogService } from './cat-service';
annotate CatalogService with @mcp;Run cds watch. The plugin creates one MCP server per @mcp-annotated service, served at an additional endpoint next to your OData endpoints. Each server provides three generic tools:
describe — lets the agent learn the entities, elements and operations of the service.
query — read access using CQL (default) or structured CQN input.
call — invokes the service's actions and functions.
CAP Java support is available via the cds-adapter-mcp dependency in srv/pom.xml.
3. Configuration flags that matter
Configuration lives under cds.mcp in package.json:
{
"cds": {
"mcp": {
"per_action_tool": true,
"prefix": true,
"format": "cql"
}
}
}per_action_tool — exposes each action/function as its own tool instead of the generic call tool. We recommend true for business actions: agents choose dedicated, well-named tools far more reliably.
prefix — prefixes tool names with the service name (e.g., CatalogService-query). Turn it on when one agent connects to several MCP servers to avoid collisions.
format — cql or cqn for query input.
4. Describe your model for the agent, not for humans
Agents are only as good as the descriptions they read. CAP picks up doc comments (recommended, Node.js) and you can customise server-level guidance with the @mcp.instructions annotation. Write them like an API contract for a junior colleague:
/** Purchase requisitions awaiting approval.
* Amounts are in document currency. Never approve above 50,000 EUR. */
entity PendingRequisitions as projection on db.Requisitions
where status = 'PENDING';
/** Approves one requisition. Requires role Approver. */
action approve(ID : UUID) returns Requisitions;5. Security: what you get for free, and what you still own
The adapter is fully integrated with CAP's existing features — authentication, @requires / @restrict authorisation, constraints and input validation all apply to MCP calls, just like OData. That is the big advantage over hand-written MCP servers.
You still own:
A dedicated agent-facing service. Don't annotate your full admin service. Create a narrow projection service for agents (read-mostly, curated fields, no personal data unless needed).
Identity flow. On BTP, protect the endpoint with XSUAA or SAP Cloud Identity Services and decide whether the agent calls with the user's token or a technical client.
SAP API Policy compliance. SAP explicitly notes the SAP API Policy still applies when data is exposed via MCP. Check licensing before exposing SAP-sourced data.
Stability. SAP positions the adapter for custom application services; for stable integration contracts keep using OData/REST. The adapter is in Beta, so pin versions and track the CAP release notes.
6. Reference architecture we deploy
S/4HANA / SuccessFactors / Ariba data reached via Destination and Connectivity services (remote services in CAP).
CAP "agent façade" service on Cloud Foundry, annotated with @mcp, with business rules and authorisation.
Consumers: a Joule Studio agent via MCP connection, a pro-code LangGraph agent, or developer tools such as Claude Code or OpenCode for local testing.
Optional: publish through the SAP Integration Suite MCP gateway when you need API-management policies, quotas and a developer portal in front.
7. Testing tip
Run locally with cds watch, connect an MCP client, and watch the CAP server log while you prompt — you'll see exactly which tool and query the agent generated. Build a regression list of 20–30 prompts and re-run it on every model or annotation change.
FAQ
Is @cap-js/mcp production ready? It was released as Beta in June 2026. Use it for pilots and controlled scenarios, pin versions, and follow the capire release notes.
Does it bypass CAP authorisation? No — MCP requests go through the same CAP service layer and authorisation checks as OData requests.
Work with us
Raven Infotech builds CAP-based agent façades and MCP endpoints for SAP S/4HANA, SuccessFactors and Ariba extensions. Ask us for a CAP + MCP readiness review of your existing BTP extensions.
Comments