Claude CodeでSAP CAPのcds-mcpを使い、CDSモデルとドキュメントを検索する

cds-mcpはClaude Codeに何を渡すサーバーか

cds-mcpは、SAP Cloud Application Programming Model(CAP)の開発を支援するMCPサーバーです。npmパッケージ名は@cap-js/mcp-serverで、リポジトリはcap-js組織にあります。AIにCAPアプリを書かせる、いわゆるエージェント型のコーディングが用途です。

READMEは、このサーバーが答えを出せる問いを次の3つで例示しています。

• プロジェクトにどのCDSサービスがあり、どこで公開されているか
• エンティティは何を表し、互いにどう関係するか
• CAP Node.jsでselect文に列を足すにはどうするか

渡されるツールは2つだけです。search_modelはコンパイル済みのCDSモデルを名前で曖昧検索します。search_docsは前処理済みのCAPドキュメントを意味検索します。

Claude Codeにとっての価値は、.cdsファイルを何本も読み込ませなくても、必要な定義だけを引ける点にあります。モデルが大きくなるほど、全文を読ませる方法はコンテキストを食います。

登録前に確かめておくこと

READMEの前提は、CAPの開発環境があることです。Requirementsの節はCAPの「Getting Started」を参照するよう案内するだけで、Nodeのバージョンなどは書かれていません。サーバーはnpxで起動するため、Node.jsとnpmが使える環境で試します。

もう1つ、READMEには注意書きがあります。Available Toolsの節の冒頭に「ツールはAIモデルが使うためのもので、安定したAPIではない」とあります。ツール名や引数を自作のスクリプトに固定する使い方は、前提にされていません。

3つのscopeで登録する

READMEは、Claude Code向けにclaude mcp addを3通り載せています。違いは--scopeだけで、起動コマンドのnpx -y @cap-js/mcp-serverは共通です。

# 全プロジェクトで使う(user scope)
claude mcp add --scope user cds-mcp -- npx -y @cap-js/mcp-server
 
# 今のプロジェクトだけ、コミットしない(local scope・既定)
claude mcp add cds-mcp -- npx -y @cap-js/mcp-server
 
# 今のプロジェクトだけ、リポジトリに入れる(project scope)
claude mcp add --scope project cds-mcp -- npx -y @cap-js/mcp-server

--は、Claude Code自身のオプションとサーバーの起動コマンドを分ける区切りです。Claude Code側の説明では、--より後ろはそのままサーバーに渡されます。

どのscopeを選ぶか

保存先と共有範囲で決まります。

CAPのリポジトリが決まっていて、チームの全員に同じ検索ツールを使わせたいなら、project scopeが合います。複数のCAPプロジェクトを行き来する個人なら、user scopeで一度だけ登録するほうが手間がかかりません。

project scopeで登録すると、プロジェクト直下の.mcp.jsonは次のような形になります(Claude Code側の説明にある.mcp.jsonの形式に、このサーバーの起動コマンドを当てはめた例です)。

{
  "mcpServers": {
    "cds-mcp": {
      "command": "npx",
      "args": ["-y", "@cap-js/mcp-server"]
    }
  }
}

同じ名前を複数のscopeに置かない

同じサーバー名を別々のscopeに、違う定義で置くと、Claude Codeは1つだけを選びます。優先順位はlocal、project、userの順で、選ばれた定義がまるごと使われます。項目の足し合わせはされません。

たとえば、userにcds-mcpを登録済みの状態で、projectにも同名で別の起動コマンドを置くと、projectの定義が勝ちます。意図しない定義で動いていないかは、claude mcp listで警告が出ていないかを見て確かめられます。

接続できたかを確かめる

登録したら、まず接続状態を見ます。

claude mcp list
claude mcp get cds-mcp

claude mcp listは、サーバーごとに✔ Connected、! Needs authentication、✘ Failed to connectなどの状態を表示します。失敗時は、claude mcp get cds-mcpのIssue:行に詳しい理由が出ます。

セッションの中では/mcpでも同じ状態を見られます。接続済みのサーバーには、ツールの数が並びます。ここにsearch_modelとsearch_docsの2つが出ていれば、準備は終わりです。

CLAUDE.mdに検索の規約を書く

登録しただけでは、Claude Codeがcds-mcpを使うとは限りません。READMEは、モデルに正しく使わせるためのルールを2つ載せています。

You MUST search for CDS definitions, like entities, fields and services (which include HTTP endpoints) with cds-mcp, only if it fails you MAY read *.cds files in the project. You MUST search for CAP docs with cds-mcp EVERY TIME you create, modify CDS models or when using APIs or the cds CLI from CAP. Do NOT propose, suggest or make any changes without first checking it.

READMEはこれをAGENTS.mdに足すよう案内しています。Claude Codeでは、プロジェクトのCLAUDE.mdに書くのが基本です。リポジトリにすでにAGENTS.mdがある場合は、Claude Codeがそれをプロジェクトの指示として読めます。

日本語のチームなら、次のように言い換えて置けます。

## CAP開発のルール
 
- エンティティ・フィールド・サービス(HTTPエンドポイントを含む)の定義は、
  まずcds-mcpのsearch_modelで探す。見つからないときだけ*.cdsを直接読む。
- CDSモデルを作る・変更するとき、およびCAPのAPIや`cds` CLIを使うときは、
  毎回search_docsでドキュメントを確認してから提案・変更する。

このルールを置く意味は、検索の順番を固定できることです。モデルの記憶だけでCAPのAPIを書かせると、バージョンが違う書き方が混ざりがちです。ドキュメント検索を先に挟めば、根拠を確かめてからコードに入る流れになります。

実際の使い方

規約を置いた状態で、たとえば次のように頼みます。

Booksエンティティの定義と、それを公開しているサービスを教えて。
そのあと、select文にauthor名の列を足す書き方をCAP Node.jsのドキュメントで確認して、修正案を出して。

この依頼は、前半がsearch_model、後半がsearch_docsに対応する作りです。どちらのツールが呼ばれたかは、Claude Codeの許可プロンプトやツール呼び出しの表示で確かめられます。

Claude Codeを介さずにCLIで使う

cds-mcpは、MCPサーバーとしてだけでなく、コマンドラインからも使えます。パッケージをグローバルに入れます。

npm i -g @cap-js/mcp-server
 
# CAPドキュメントを検索(READMEの例。末尾の1は件数の指定)
cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1
 
# CDSモデルの定義を検索(READMEの例。カレントのプロジェクトでBooksを探す)
cds-mcp search_model . Books entity

この方法は、検索結果を人が先に確かめたいときや、ツールが期待どおりの定義を返すかを切り分けたいときに向きます。MCPの接続問題とサーバー自体の問題を分けて調べられるためです。

環境変数で挙動を調整する

READMEには4つの環境変数があります。search_docsはローカルで埋め込みを使うため、ネットワークまわりの設定が中心です。

社内ネットワークなどで外部への接続が遅い、あるいは制限されている環境では、タイムアウトの値を伸ばす余地があります。更新の確認を止めたいならCDS_MCP_OFFLINE=trueです。ただしこの設定は、キャッシュ済みの埋め込みがあることが前提になります。

Claude Codeに環境変数を渡すには、claude mcp addの--envを使います。

claude mcp add cds-mcp --env CDS_MCP_OFFLINE=true -- npx -y @cap-js/mcp-server

プラグインとして入れる方法もある

Claudeのマーケットプレイスにも、cds-mcpというプラグインが載っています。説明は「SAP CAPプロジェクトのAI支援開発。CDSモデルとCAPドキュメントを検索する」で、ページには「Install in Claude Code」の導線があります。

手動のclaude mcp addとの違いは、サーバーの管理の仕方です。プラグインで入れたサーバーは、/mcpではなくプラグインの導入・削除で出し入れします。/mcpのトグルで一時的に切ることはできます。

迷ったら、次の基準で選べます。

• チームの.mcp.jsonで起動コマンドをそろえたい: claude mcp add --scope project
• 自分だけが、手早く入れたい: プラグイン、またはuser scopeのclaude mcp add
• 環境変数やタイムアウトを細かく調整したい: 起動コマンドを自分で書けるclaude mcp add

つまずきやすい点

他のSAP向けMCPサーバーとどう使い分けるか

SAP関連のMCPサーバーは、開発する対象ごとに分かれています。

CAPでバックエンドのサービスを作り、その上にFiori elementsの画面を載せる構成なら、cds-mcpとFiori MCPサーバーを並べて登録できます。名前が重ならない限り、サーバーは共存できます。

まとめ

cds-mcpの導入は、claude mcp addの1行と、CLAUDE.mdへの2行の規約で完了します。効果が出るかどうかは、登録よりも規約にかかっています。モデルに定義検索とドキュメント確認を先に行わせる指示がなければ、ツールが使われないまま記憶で書かれる可能性が残ります。

共有したい場合はproject scope、個人利用ならuser scopeで登録し、claude mcp listで接続を確認してから、規約を置いて試してください。