ahinleew-aivju833 Using the PPDB MCP server
Overview
The PPDB MCP server exposes five Sobrus project documents (Word, PowerPoint, three Excel workbooks) as 15 read-only tools. Content is French and returned verbatim.
Never answer PPDB questions from memory or inference. Always call a tool. The whole point of this server is that answers are traceable to the source documents.
Where it runs
The server is deployed on Cloudflare Workers and is the one to use:
https://ppdb-mcp.ppdb-sobrus.workers.dev/mcp
It is already configured at user scope, so it is available in every project without setup. If a session does not show it, add it once:
claude mcp add --transport http --scope user ppdb https://ppdb-mcp.ppdb-sobrus.workers.dev/mcp --header "Authorization: Bearer <TOKEN>"
--scope user is what makes it available in every project, not just one.
Health check needs no token:
curl https://ppdb-mcp.ppdb-sobrus.workers.dev/health
Requests without a valid bearer token get 401. The data is a build-time snapshot —
generatedAt in ppdb_list_documents and /health tells you how fresh it is.
Pick the right tool
| The question is about… | Call |
|---|---|
| What documents exist | ppdb_list_documents |
| Required product fields, DCI, TVA, barcodes | ppdb_get_data_model |
| Data-quality rules, inconsistencies, severities | ppdb_list_anomaly_rules |
| Where data comes from, AMMPS, suppliers | ppdb_list_sources |
| Tasks, owners, deadlines, progress | ppdb_list_tracker_actions |
| A whole workpackage (WP0–WP5) | ppdb_get_workpackage |
| Who decides / approves / is consulted | ppdb_get_raci |
| Rules for changing the database | ppdb_get_governance_rules |
| Why the project exists, audit figures | ppdb_get_audit_metrics |
| Overall progress | ppdb_get_project_status |
| Phases, timeline, M+N | ppdb_get_roadmap |
| Risks and mitigations | ppdb_list_risks |
| How updates flow, who does what step | ppdb_get_update_workflow |
| Anything else, or an exact phrase | ppdb_search |
| Raw content of one sheet/section/slide | ppdb_read_document |
Quick reference
Every tool takes fmt (markdown default, json for structured data). Filters are
accent-insensitive — medicament matches Médicament.
ppdb_list_anomaly_rules(severite="Critique", famille="Prix")
ppdb_list_tracker_actions(wp="WP1", statut="À faire")
ppdb_get_workpackage(wp="WP3")
ppdb_get_raci(role="Data")
ppdb_search(query="AMMPS", document="sources")
ppdb_read_document(document="plan_action", part="Tracker", limit=20)
Paginated tools: ppdb_read_document, ppdb_search, ppdb_get_data_model,
ppdb_list_anomaly_rules, ppdb_list_sources, ppdb_list_tracker_actions,
ppdb_list_risks. They return has_more and next_offset — follow them rather
than reporting a partial list as complete.
Prefer typed tools over raw reads
ppdb_search and ppdb_read_document return raw text you then have to interpret.
The twelve typed tools return already-structured rows. Reach for ppdb_search when
no typed tool covers the question, not as a first move.
Common mistakes
Answering from the conversation instead of calling a tool. Figures like the audit
percentages or rule counts must come from ppdb_get_audit_metrics /
ppdb_list_anomaly_rules every time.
Translating the data. DCI, PPV, PPH, AMM, forme galénique and the emoji
markers (⬜ À faire, 🔴 Critique) are values, not decoration. Quote them as-is.
Reporting page one as the whole answer. Check has_more.
Assuming a document section is empty. Four top-level headings hold no text of
their own; include_subsections defaults to true and handles this. If you passed
false and got a bare heading, that is why.
Guessing a document name. Slugs are cadrage, flow_ia, plan_action,
sources, onboarding_plan. An error lists the valid ones — read it.
The one tool worth knowing about
ppdb_get_workpackage joins a workpackage's narrative definition (Word scoping
document) with its live execution state (tracker rows + dashboard counts). No single
source file contains that view. For "how is WP2 going and what's left", it is one
call instead of four.