Connect to the BeamScope MCP server running in your Elixir application. The TCP port is pre-configured via BEAM_SCOPE_MCP_PORT env var. Do NOT guess the port. If connection fails, look up the correct port in the Elixir config: check config/runtime.exs, config/dev.exs, or config/config.exs in the current project for config :beam_scope_mcp, port: <number>. Then check .mcp.json to ensure the BEAM_SCOPE_MCP_PORT env var matches. This must be called before using other BeamScope tools (get_logs, project_eval, etc.).

Check if connected to an Elixir app and get server details. The port is configured via BEAM_SCOPE_MCP_PORT env var — if not set, check your .mcp.json env config.

Your primary debugging tool. Retrieve application logs from the running Elixir app — errors, warnings, crash reports, and application output. This is the ONLY source of log data; no other tool provides it.

WHEN TO USE: First step when diagnosing any problem. Check logs before drawing conclusions from other tools. NOT FOR: System resource usage (use get_system_stats). Process-level details (use get_process_info).

Use grep to filter (e.g. "error", "warning", "timeout") and level to filter by severity. Logs are in a circular buffer so old entries may be discarded.

Evaluate Elixir code in the context of the running application. This is the general-purpose escape hatch — use it when no specific tool exists for what you need.

PREFER specific tools over project_eval when they exist:

• Need logs? Use get_logs, not project_eval with Logger

• Need process info? Use get_process_info/get_process_state, not project_eval with Process.info

• Need to recompile? Use recompile or reload_module

• Need ETS data? Use list_ets_tables/inspect_ets_table

• Need docs? Use get_docs

• Need callers? Use xref_callers

Use project_eval for one-off operations that don't have a dedicated tool. The code runs with full access to your application's modules, dependencies, and runtime state.

Get @moduledoc/@doc documentation for an Elixir module or function. Reads from compiled .beam files (local, no network).

WHEN TO USE: You need to understand what a function does, its parameters, or how to use a module. NOT FOR: Finding what calls a function (use xref_callers). Evaluating code (use project_eval).

Examples: "GenServer", "String.split", "String.split/2", "c:GenServer.handle_call/3" (prefix c: for callbacks).

Recompile the entire project from within the running BEAM. Returns errors/warnings.

WHEN TO USE: After changing multiple files, or when you're not sure what changed. This is equivalent to mix compile. NOT FOR: Single file changes (use reload_module instead — much faster). Dependencies (use recompile_deps instead).

Hot-reload a single module from its source file. Fastest possible feedback loop — change one file, reload it, test immediately.

WHEN TO USE: After changing a single .ex file. No full recompile needed. NOT FOR: Multiple file changes (use recompile). Dependencies (use recompile_deps).

Get BEAM runtime health: memory usage, scheduler count, process/port/atom counts, uptime, IO throughput.

WHEN TO USE: You want a system-level health snapshot — is memory growing? How many processes are running? How long has the app been up? NOT FOR: Application configuration (use get_app_config). Individual process details (use get_process_info). Checking for errors (use get_logs — system stats don't show errors).

List running BEAM processes — find them by name, sort by memory or queue size. Returns summary info for each process.

WHEN TO USE: You need to discover what processes exist, find a specific process by name, or identify processes using the most memory/having the largest queues. NEXT STEP: Once you have a PID or name, use get_process_info, get_process_state, or get_process_dictionary for details.

Get metadata ABOUT a process: what function it's running, memory usage, message queue length, links, monitors, stacktrace.

WHEN TO USE: You want to know what a process IS and what it's DOING — its identity and vital signs. NOT FOR: The data the process is holding (use get_process_state). Metadata in the process dictionary (use get_process_dictionary). Use list_processes first to find PIDs/names if you don't know them.

Get the DATA a GenServer is holding — its internal state (the value in the GenServer's loop).

WHEN TO USE: You want to see the actual data/state inside a process — what it's storing, its current values. NOT FOR: Process metadata like memory/links/stacktrace (use get_process_info). Process dictionary entries (use get_process_dictionary). Note: may timeout if the process is busy or doesn't support :sys messages.

Read the process dictionary — hidden metadata stored outside the main state. Contains OTP internals like $ancestors, $initial_call, plus any custom entries (Logger metadata, step context, flags).

WHEN TO USE: You need metadata that isn't in the GenServer state — OTP ancestry, custom flags, or debugging context. NOT FOR: The process's main data (use get_process_state). Process vitals like memory/stacktrace (use get_process_info).

Force recompile Elixir dependencies (not the project itself).

WHEN TO USE: When a local path dependency's source has changed, or to force-rebuild a specific dep. You MUST specify the args parameter. NOT FOR: Project code (use recompile or reload_module).

Get runtime application configuration — what the BEAM actually has loaded (not what's in the config files on disk). Includes runtime.exs overrides, env var substitutions, and dynamic Application.put_env changes.

WHEN TO USE: You need to check config values (ports, feature flags, module settings) as the running app sees them. NOT FOR: System health metrics (use get_system_stats). Process-level inspection (use get_process_info/state).

Get the OTP supervision tree for an application. Recursively walks supervisors showing the full hierarchy of processes with PIDs, types, and child counts.

You MUST specify the app name. Use get_app_config or project_eval with Application.started_applications() to find app names if unsure.

List all ETS tables with metadata: name, row count, memory, type, protection, owner. Sorted by memory descending.

WHEN TO USE: Discover what ETS tables exist, find tables using the most memory. NEXT STEP: Use inspect_ets_table with the table name to read its contents.

Read the contents of an ETS table. Returns rows from the table, limited to avoid massive output.

Use list_ets_tables first to find table names, then inspect specific tables.

Find all callers of a module or function across the project — "what depends on this?"

WHEN TO USE: Impact analysis before refactoring. "What breaks if I change this function?" "Who calls this module?" NOT FOR: Understanding what a function does (use get_docs). Seeing runtime call flow (use trace_calls).

Start tracing function calls on a module. This tool does NOT return the trace results directly — it writes them to a file and returns the file path.

WORKFLOW:

1. Call this tool → you get back a file path (e.g. /tmp/beam_scope_traces/MyModule_20260323_221503.log)

2. Wait a few seconds for the trace to collect events

3. Read the file using your normal file reading tools (Read tool) to see the trace results

4. The trace auto-stops when it hits max_calls or max_seconds — you do NOT need to call stop_trace

WHY A FILE: Traces collect events over time and can be large. Writing to a file lets you read just the parts you need (head, tail, grep for patterns).

The file contains timestamped entries like: [22:15:03.001] #1 #PID<0.599.0> MyModule.my_function("arg1", 42)

All parameters except function are REQUIRED. max_calls capped at 200, max_seconds capped at 30.

Abort a running trace early. You do not normally need to call this — traces auto-stop when they hit their max_calls or max_seconds limit and clean up after themselves. This is only useful if you want to cancel a trace before it finishes on its own. Safe to call even if no trace is running.