SQL Commenter

SQLCommenter is an open-source convention that propagates application context into the database by prepending a structured comment to every SQL statement before it is executed. The comment is stripped before query planning, so it has no effect on results — but it shows up verbatim in database query logs and slow-query logs, letting you correlate a specific SQL statement back to the MCP client, LLM tool invocation, model, user, agent, and distributed trace that triggered it.

This closes the observability gap between the application-level traces emitted by Toolbox and the database-level logs emitted by your underlying database engine.

Enabling SQL Commenter

SQL Commenter is opt-in and disabled by default. Enable it on a per-source basis by setting the sqlCommenter field to true in a source’s configuration file:

sources:
  - name: my-pg-source
    type: postgres
    # ...
    sqlCommenter: true

If you are exporting telemetry using OpenTelemetry, the traceparent attribute embedded in the SQL comment will automatically be part of the same distributed trace exported by Toolbox:

./toolbox --telemetry-otlp="127.0.0.1:4553"

Supported Sources

SQL Commenter is supported on the following database sources:

• alloydb-postgres
• cloud-sql-postgres
• cloud-sql-mysql
• postgres
• mysql
• sqlite

Comment Format

When enabled, Toolbox prepends a SQLCommenter-format comment to every SQL statement executed against a supported source. Keys are sorted alphabetically, values are URL-encoded, and pairs are joined by commas inside a /* … */ block. For example:

/*client='toolbox-langchain-python%2Fv0.1.0',client.model='gemini-2.5-flash',db.system.name='postgresql',server='genai-toolbox%2F1.1.0',tool.name='search_user',traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'*/ SELECT * FROM users WHERE id = $1;

Attributes

Client-supplied attributes (client, client.model, client.user.id, client.agent.id) are populated from the MCP request’s params._meta["dev.mcp-toolbox/telemetry"] field. Attributes that are not provided by the client or not applicable in the current context are omitted from the comment.

Populating Client Attributes from SDKs

Toolbox SDKs that support the dev.mcp-toolbox/telemetry meta field will populate client.* attributes automatically. With the Python SDK, you can attach per-tool attributes such as model name, user ID, and agent ID using TelemetryAttributes. See Per-call Telemetry Attributes for details.