Debugging AI Coding Agents: Mastering the MCP Process

Prerequisites and Key Tools

To follow this guide, you should be familiar with the following:

• Claude Code: The CLI-based agent for Anthropic's Claude models.
• Laravel Framework: Specifically the Laravel Boost package.
• MCP Architecture: Understanding how tools provide external data to LLMs.
• Terminal Shortcuts: Familiarity with CLI navigation and command flags.

Debugging Technique 1: Real-Time Inspection

When Claude Code is running a task, it often hides the raw data exchange behind a progress bar. However, visibility is your best friend when an agent seems "stuck" or slow.

The Expand Command

While the agent is working, use the following shortcut to see exactly what is happening under the hood:

• Ctrl + O: This expands the current tool output.
• Ctrl + E: This allows you to browse earlier messages in the session history.

By expanding the output, you can inspect the raw JSON returned by an MCP tool. In one instance, a database schema tool meant to fetch tables for a single Laravel project was actually returning every table from the entire local MySQL server—150 tables instead of the expected 10. This visibility immediately identifies the source of token bloat.

Debugging Technique 2: Prompt-Based Analysis

You can actually instruct the AI to perform self-monitoring. By appending specific instructions to your prompt, you force the model to report its own resource usage.

[Your Task Description Here]

When done, list all MCP tools used and their specific token counts.

This creates a post-execution report where the agent analyzes its own logs. It provides an estimated token usage per tool call, making it easy to spot "heavy" calls. For example, a single database schema fetch might consume 10,000 tokens (5% of a 200k context window), which is a clear signal that the tool needs better filtering or scoped queries.

Syntax and Tips

When writing custom MCP tools or using external ones like those in GitHub repositories, always implement filters. If a tool fetches a database schema, it should accept a tables filter to limit scope.

Best Practices:

• Verify Scoping: Ensure the tool only accesses the current project's environment variables.
• Monitor Tokens: Keep an eye on the 200k context limit; excessive MCP noise will cause the agent to "forget" earlier instructions.
• Contribute Back: If you find a bug in an open-source MCP like Laravel Boost, document the JSON output and submit a pull request.