3.7 Monitoring the SQLcl MCP Server

Learn how you can monitor the health, status, and activity of your SQLcl MCP Server.

3.7.1 Checking Server Status

When the SQLcl MCP Server starts successfully, it displays a confirmation message with the startup timestamp, indicating it’s ready to accept connections from the MCP client.

You can verify this message on the terminal to confirm server readiness. Here's an example server message on startup:

SQL>./sql -mcp
---------- MCP SERVER STARTUP ----------
MCP Server started successfully on Fri Jun 13 13:52:13 WEST 2025
Press Ctrl+C to stop the server
----------------------------------------

3.7.2 Tracking Activity with Logs

The SQLcl MCP Server provides two main ways to track and monitor database operations: a historical audit trail and real-time session monitoring.

Reviewing the Audit Trail

The server automatically records the execution history of every request in the DBTOOLS$MCP_LOG table. This table provides a complete audit trail of all database operations the server performs. It captures request details, execution times, and results to help you with analysis and troubleshooting.

To maintain optimal database performance, you should prune the DBTOOLS$MCP_LOG table regularly. Consider setting a record limit (for example, 1000 records) and creating an automated cleanup procedure to prevent excessive log accumulation.

To view the audit trail, run a query similar to the following example:

SQL> SELECT ID, MCP_CLIENT, MODEL, END_POINT_TYPE, END_POINT_NAME, LOG_MESSAGE
  2*      FROM DBTOOLS$MCP_LOG;

   ID MCP_CLIENT    MODEL              END_POINT_TYPE    END_POINT_NAME    LOG_MESSAGE
_____ _____________ __________________ _________________ _________________ __________________________
    3 Claude        claude-sonnet-4    tool              connect           Connect to HR
    4 Claude        claude-sonnet-4    tool              run-sql           select /* LLM in use is Claude Sonnet 4 */ * from employees
    5 Claude        claude-sonnet-4    tool              run-sqlcl         info employees
    6 Claude        claude-sonnet-4    tool              disconnect        Disconnect from HR

SQL>

Monitoring Live Sessions

If you have database administrator (DBA) privileges, you can monitor active MCP connections and operations in real-time. The server integrates with Oracle's V$SESSION view, allowing you to use standard Oracle monitoring tools to track current sessions, resource usage, and performance. To see the MCP client information, you can observe the MODULE and ACTION values in V$SESSION.

To view active sessions, query the V$SESSION view:

select * from V$SESSION;

3.7.3 Monitoring Through Your Client

Your MCP client provides the most direct way to monitor server activity.

For example, in an application like Claude Desktop, the log files capture detailed information about the server's operations, including:

  • Connection events
  • Tool executions
  • Query results
  • Error messages

Always check your client's logs first when you need to troubleshoot an issue.

3.7.4 Assessing Server Health Through Performance

You can gauge server health by observing its performance.

  • Normal Operation: Under normal operation, you should experience consistent response times and smooth database operations.
  • Potential Issues: If you are experiencing issues, you may notice delayed responses, connection errors, or incomplete results. If these occur, check your client's logs to begin troubleshooting.