Complete reference for CAP MCP server tools (search_model, search_docs) with usage examples
Provides AI agents with live access to CAP projects through model and documentation search tools.
/plugin marketplace add secondsky/sap-skills/plugin install sap-cap-capire@sap-skillsComplete reference for the official @cap-js/mcp-server tools that provide AI agents with live access to your CAP project.
The CAP MCP (Model Context Protocol) server exposes two powerful tools:
Package: @cap-js/mcp-server
Installation: npx -y @cap-js/mcp-server
License: Apache-2.0
Fuzzy search for CDS definitions in your project's compiled Core Schema Notation (CSN) model.
Use Case 1: Entity Discovery
search_model(query="orders", type="entity")Use Case 2: Service Endpoint Discovery
search_model(query="CatalogService", type="service")Use Case 3: Association Validation
search_model(query="Books.associations")Use Case 4: Action Signature Lookup
search_model(query="submitOrder", type="action")User: "Add a bound action to Books entity to mark as bestseller"
Agent: Let me check the Books entity structure first.
[Calls: search_model(query="Books", type="entity")]
Result: Books entity has ID, title, author_ID, stock fields
Agent: Now I'll check how to define bound actions.
[Calls: search_docs(query="define bound action in CDS")]
Result: Bound action syntax documentation
Agent: Here's how to add the action...
Semantic search through preprocessed SAP CAP documentation using vector embeddings.
Use Case 1: Syntax Lookup
search_docs(query="composition syntax CDS")Use Case 2: API Pattern Discovery
search_docs(query="register before create handler nodejs")Use Case 3: Deployment Configuration
search_docs(query="multitenancy HANA configuration")Use Case 4: Best Practice Lookup
search_docs(query="pagination best practices CAP")User: "Implement input validation for Books.stock field"
Agent: Let me find the validation patterns.
[Calls: search_docs(query="input validation CDS annotations")]
Result: @assert.range annotation documentation
Agent: [Calls: search_docs(query="validation in event handlers nodejs")]
Result: req.error() and srv.before() patterns
Agent: Here are two approaches for validation...
Uses:
search_model - Find existing entities, check associationssearch_docs - Look up CDS syntax, annotation patternsExample: "Create entity Products with category association"
search_model(query="Categories", type="entity") to find target entitysearch_docs(query="association syntax CDS") for association syntaxUses:
search_model - Find service definitions, action signaturessearch_docs - Look up event handler API, CQL syntaxExample: "Implement custom CREATE handler for Orders"
search_model(query="Orders", type="entity") to understand entitysearch_docs(query="before create handler registration nodejs") for APIUses:
search_model - Check project structure, service bindingssearch_docs - Look up deployment config, multitenancy setupExample: "Configure Cloud Foundry deployment"
search_docs(query="cloud foundry deployment mta") for MTA configsearch_docs(query="hana service binding") for database setupUses:
search_model - Analyze entity relationships for query optimizationsearch_docs - Look up performance patterns, debugging techniquesExample: "Why is this query slow?"
search_model to understand entity associationssearch_docs(query="query optimization N+1 problem CAP") for patterns{
"sap-cap-capire": {
"command": "npx",
"args": ["-y", "@cap-js/mcp-server"],
"env": {}
}
}
{
"mcpServers": {
"cap-mcp": {
"command": "npx",
"args": ["-y", "@cap-js/mcp-server"],
"env": {}
}
}
}
{
"mcp": {
"cap-mcp": {
"type": "local",
"command": ["npx", "-y", "@cap-js/mcp-server"],
"enabled": true
}
}
}
{
"servers": {
"cap-mcp": {
"command": "npx",
"args": ["-y", "@cap-js/mcp-server"],
"env": {},
"type": "stdio"
}
}
}
CRITICAL RULES (from official documentation):
Always search model first: You MUST search for CDS definitions with search_model first. Only read .cds files if search_model fails.
Always search docs before coding: You MUST search for CAP docs with search_docs EVERY TIME you create or modify CDS models or use CAP APIs. Do NOT propose changes without checking documentation first.
Trust MCP tools over file reads: MCP tools search the compiled model (CSN), which is the source of truth. File reads may not reflect the final compiled model.
Solution:
# Install globally for faster access
npm install -g @cap-js/mcp-server
# Or use npx (auto-installs)
npx -y @cap-js/mcp-server
Possible Causes:
cds build)Solution: Run cds compile srv/ --to csn to verify model compilation
Possible Causes:
Solution: Rephrase query with more specific technical terms
You can also use MCP tools directly from command line:
# Install globally
npm i -g @cap-js/mcp-server
# Search compiled model
cds-mcp search_model . Books entity
# Search CAP documentation
cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1