scout_apm_mcp.rb

This MCP server provides a Ruby-based ScoutAPM API client wrapped as an MCP server. It exposes tools to fetch traces, endpoints, metrics, errors, and insights from ScoutAPM via the MCP protocol, enabling MCP-enabled clients (like Cursor IDE or Claude Desktop) to interact with ScoutAPM data. The server runs as a Ruby gem and authenticates using API keys sourced from environment variables or 1Password integration (via opdotenv) and, optionally, the 1Password CLI. To use it, configure the MCP client to point at the server and provide credentials through OP_ENV_ENTRY_PATH or environment variables. You can test and inspect its behavior with MCP Inspector before connecting real clients. The server communicates over STDIN/STDOUT, so it can be proxied by the MCP inspector and integrated into your development workflow.

Prerequisites:

• Ruby 3.1 or higher
• RubyGems (bundler is optional but recommended)

Step-by-step installation:

1. Install the ScoutAPM MCP gem:

gem install scout_apm_mcp

2. If you use Bundler in a project, you can run the MCP server via Bundler:

bundle exec scout_apm_mcp

3. Or install and run the server globally:

gem install scout_apm_mcp
scout_apm_mcp

4. Ensure your MCP client configuration points to the server command (see mcp_config for example) and that credentials are available either via OP_ENV_ENTRY_PATH or environment variables like API keys.
5. Optional: upgrade to the latest version when needed:

gem update scout_apm_mcp

Tips and common issues:

• Do not store API keys directly in MCP configuration files. Prefer OP_ENV_ENTRY_PATH (1Password integration) or environment variables (API_KEY/SCOUT_APM_API_KEY). The MCP gem will fetch credentials from these sources automatically.
• If you use a Ruby version manager (e.g., mise or rbenv), set RUBY_VERSION to match your environment to ensure the correct Ruby is used when invoking gem exec.
• The MCP server communicates via STDIN/STDOUT. When testing with MCP Inspector, you can verify available tools and their parameters before integrating with clients.
• As of v0.1.3, client methods return extracted data (arrays/hashes) rather than full API response structures. This is a breaking change from earlier versions.
• For Cursor IDE or Claude Desktop, ensure the MCP configuration is loaded and restart the client after changes.
• If you encounter permission or PATH issues running gem exec, ensure your shell can locate the Ruby environment and the gem executable.
• Use the MCP Inspector tool to validate the server's capabilities and view request/response messages during development.