Native Observability via MCP¶
Site owners ask AI agents why a page is slow. The agent cannot see the data the module collects, so it guesses. Giving it database or admin access would show it far more than it needs.
The submodule native_observability_mcp gives the agent that data through MCP Server and the Tool API. It is read-only: no tool writes.
What the site owner controls¶
The site owner picks what leaves the site:
- Grade 0: nothing.
- Grade 1: aggregates by route name.
- Grade 2: request details, filtered by the privacy policy. After the declaration is recorded, a client must sign in again and ask for
observability:raw: a refresh never adds it, and tokens issued before keep their scopes.
Clients connect with OAuth 2.1 and PKCE. A new client waits for admin approval (the Approve button in the MCP tab) before it can read anything. Registration is closed on a new site: open it and raise the grade first. A vocabulary tool tells the agent how to read each field. Every call is logged, allowed or refused.
Tools¶
| Tool | What it does | Scope |
|---|---|---|
vocabulary_read |
Explains units, terms, limits and the active grade | observability:mcp:connect |
routes_slowest |
Lists the slowest routes in a period | observability:read |
routes_compare_periods |
Compares route performance between two periods | observability:read |
cache_explain_misses |
Explains cache misses by route | observability:read |
queries_slowest |
Lists the slowest database statements | observability:read |
overhead_report |
Reports the overhead the module measured on the site | observability:read |
traces_list |
Lists individual request traces (grade 2) | observability:raw |
cache_events_list |
Lists individual cache events (grade 2) | observability:raw |
On the wire the tool names carry the prefix tool_api__, for example tool_api__routes_slowest. A tools/call with the bare name answers "Tool not found".
The module also ships three prompts: diagnose_slow_route, explain_cache_miss and compare_periods.
Requirements¶
- Drupal ^11 and PHP 8.3 or later for the submodule.
- A site served over HTTPS on the standard port: the issuer of the discovery documents is always
https://host/. Settrusted_host_patternstoo, or the MCP tab warns. - Contrib modules:
tool,mcp_server,mcp_server_tool_bridge,mcp_server_oauth,simple_oauth(6.1.4 or later) andsimple_oauth_21(which provides PKCE, server metadata and dynamic client registration). - The base module and its span, metrics, cache observer and database observer submodules.
The recipe in recipes/native_observability_mcp installs the set. See Minimal stack. Connect each client as a dedicated user with a role that has only the MCP permissions it needs.
Admin pages¶
| Page | Path |
|---|---|
| Exposure grade | /admin/config/development/native-observability/exposure |
| MCP server: approve and revoke clients | /admin/config/development/native-observability/settings/mcp |
| MCP calls: the call log | /admin/reports/native-observability/mcp-calls |
More pages¶
- Minimal stack: modules, recipe and compatibility.
- Vocabulary: what the agent is told, tool by tool.
- Data map: every stored field and how each grade treats it.
- Privacy notice: what leaves the site at each grade, with a text for your privacy page.
- Testing: how the tools and the stack are tested.