MCP Server (Preview)

The pganalyze MCP (Model Context Protocol) server allows AI assistants to interact with your pganalyze data. This enables AI coding tools like Claude Code, Codex, or Cursor to query server metrics, inspect EXPLAIN plans, run the Index Advisor, and review active issues.

For a demo of the MCP server in action, watch the webinar recording:

Setup

Claude Code

Add the pganalyze MCP server using the CLI:

claude mcp add --transport http pganalyze https://app.pganalyze.com/mcp

Codex

Add the pganalyze MCP server using the CLI:

codex mcp add pganalyze --url https://app.pganalyze.com/mcp

Cursor

In Cursor settings, add a new MCP server with the following configuration:

{
  "mcpServers": {
    "pganalyze": {
      "url": "https://app.pganalyze.com/mcp"
    }
  }
}

Other MCP clients

MCP clients that support HTTP transport can connect to the pganalyze MCP server at https://app.pganalyze.com/mcp. Refer to your client's documentation for how to configure HTTP-based MCP servers.

If you're using an MCP client hosted on the web (instead of running locally) the OAuth redirect URI may not be permitted and you will get an authentication error during OAuth Dynamic Client Registration (DCR). Reach out to pganalyze support to verify the permitted redirect URIs.

Authentication

The MCP server supports two authentication methods: OAuth (interactive) and API key (non-interactive).

OAuth (recommended)

When you first connect, your MCP client will open an OAuth authorization flow through your pganalyze account. During authorization, you can choose between two permission levels:

• Basic read access (always granted): Read access to your account data, excluding sensitive information such as query text and EXPLAIN plans.
• Full read access (optional): Full read access to your account data, including query text and EXPLAIN plans.

Access is further limited by your account permissions. For example, if you can only view certain servers, the MCP server will have the same restriction.

API key

As an alternative to OAuth, you can authenticate using a pganalyze read API key. This gives full read access to your account data, equivalent to granting the "Full read access" OAuth permission.

To use API key authentication, first create an API key, then configure your MCP client to pass the key as a Bearer token in the Authorization header. For example, with Claude Code:

claude mcp add --transport http \
  pganalyze https://app.pganalyze.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"

The exact configuration for other MCP clients depends on how they support custom headers. Refer to your client's documentation for details.

Since API key authentication does not require interactive authorization, it is suited for scenarios where OAuth is impractical, for example, automated background agents, CI/CD pipelines, or other programmatic integrations that run without user interaction.

Rate limiting

During the preview, the MCP server is limited to 100 requests per billable server per hour per organization, regardless of authentication method. If you exceed this limit, requests will be rejected until the quota gradually refills over time. This limit may be adjusted as we learn more about common use cases and usage patterns.

Available tools

The MCP server exposes tools, organized by the type of data they access. Since this feature is in preview, the available tools and their parameters may change.

Example use cases

• Investigate slow queries during development: Ask your AI tool to pull the top queries by runtime for a specific database using get_query_stats, then inspect EXPLAIN plans for a query that regressed using get_query_explains and get_query_explain.
• Review active issues: Check the current check-up status for a database using get_checkup_status to see if there are unresolved alerts, such as insufficient VACUUM frequency or unused indexes.
• Trace a slow request to its query plan: If your application uses OpenTelemetry tracing, resolve a trace span to the corresponding EXPLAIN plan using get_query_explain_from_trace to understand why a specific request was slow.