Scout MCP Local

🚀 Scout Monitoring MCP

This repository provides code to locally run an MCP server, enabling access to Scout Monitoring data via Scout's API. A Docker image is available for your AI Assistant to pull and run, putting Scout Monitoring's performance and error data directly at your AI Assistant's disposal, applicable to Rails, Django, FastAPI, Laravel and more.

🚀 Quick Start

To start using the Scout Monitoring MCP, you need to have a Scout Monitoring account and an API key, and install Docker. The following sections will guide you through the process.

✨ Features

• Direct Access to Data: Put Scout Monitoring's performance and error data directly in the hands of your AI Assistant.
• Multi - language Support: Compatible with Ruby, Python, PHP and more.
• Rich Toolset: Provides various tools to access Scout APM data, such as list_apps, get_app_metrics, etc.
• Interactive Setup: Use the setup wizard to easily configure and start using the Scout MCP.

📦 Installation

We recommend using the provided Docker image to run the MCP server. The Docker image is available on Docker Hub.

Of course, you can also clone this repo and run the MCP server directly. It is recommended to use uv or other environment management tools.

Prerequisites

• Scout Monitoring Account:
  1. Sign up.
  2. Install the Scout Agent in your application and send Scout data.
     • Ruby
     • Python
     • PHP
     • If you are trying this out locally, make sure monitor: true, errors_enabled: true are set in your config for the best experience.
  3. Visit settings to get or create an API key.
     • This is not your "Agent Key"; it's the "API Key" that can be created on the Settings page.
     • This is a read - only key that can only access data in your account.
• Docker Installation: Instructions below assume you can start a Docker container.

The MCP server will not currently start without an API key set, either in the environment or by a command - line argument on startup.

Setup Wizard

The simplest way to configure and start using the Scout MCP is with our interactive setup wizard:

Run via npx

npx @scout_apm/wizard

Build and run from source

cd ./wizard
npm install
npm run build
node dist/wizard.js

The wizard will guide you through:

• Selecting your AI coding platform (Cursor, Claude Code, Claude Desktop).
• Entering your Scout API key.
• Automatically configuring the MCP server settings.

Supported Platforms

The wizard currently supports setup for:

• Cursor - Automatically configures MCP settings.
• Claude Code (CLI) - Provides the correct command to run.
• Claude Desktop - Updates the configuration file for Windows/Mac.

Configure a local Client (e.g. Claude/Cursor/VS Code Copilot)

If you would like to configure the MCP manually, this usually just means supplying a command to run the MCP server with your API key in the environment to your AI Assistant's config. Here is the shape of the JSON (the top - level key varies):

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

claude mcp add scoutmcp -e SCOUT_API_KEY=your_scout_api_key_here -- docker run --rm -i -e SCOUT_API_KEY scoutapp/scout-mcp-local

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

Token Usage

We are currently more interested in expanding available information than strictly controlling response size from our MCP tools. If your AI Assistant has a configurable token limit (e.g. Claude Code export MAX_MCP_OUTPUT_TOKENS=50000), we recommend setting it generously high, e.g. 50,000 tokens.

💻 Usage Examples

Basic Usage

Scout's MCP is intended to put error and performance data directly in the hands of your AI Assistant. Use it to get traces and errors with line - of - code information that the AI can use to target fixes right in your editor.

Most assistants will show you both raw tool calls and perform analysis. Desktop assistants can readily create custom JS applications to explore whatever data you desire. Assistants integrated into code editors can use trace data and error backtraces to make fixes right in your codebase.

Advanced Usage

Combine Scout's MCP with your AI Assistant's other tools to:

• Create rich GitHub/GitLab issues based on errors and performance data.
• Make JIRA fun - have your AI Assistant create tickets with all the details.
• Generate PRs that fix specific errors and performance problems.

Tool

The Scout MCP provides the following tools for accessing Scout APM data:

• list_apps - List available Scout APM applications, with optional filtering by last active date.
• get_app_metrics - Get individual metric data (response_time, throughput, etc.) for a specific application.
• get_app_endpoints - Get all endpoints for an application with aggregated performance metrics.
• get_endpoint_metrics - Get timeseries metrics for a specific endpoint in an application.
• get_app_endpoint_traces - Get recent traces for an app filtered to a specific endpoint.
• get_app_trace - Get an individual trace with all spans and detailed execution information.
• get_app_error_groups - Get recent error groups for an app, optionally filtered by endpoint.
• get_app_insights - Get performance insights including N + 1 queries, memory bloat, and slow queries.

Useful Prompts

• "Summarize the available tools in the Scout Monitoring MCP."
• "Find the slowest endpoints for app my-app-name in the last 7 days. Generate a table with the results including the average response time, throughput, and P95 response time."
• "Show me the highest - frequency errors for app Foo in the last 24 hours. Get the latest error detail, examine the backtrace and suggest a fix."
• "Get any recent n + 1 insights for app Bar. Pull the specific trace by id and help me optimize it based on the backtrace data."

🔧 Technical Details

We use uv and taskipy to manage environments and run tasks for this project.

Run with Inspector

uv run task dev

Connect within inspector to add API key, set to STDIO transport.

Build the Docker image

docker build -t scout-mcp-local .