Shocm's Blog
• 6 min read

Tinkerwell 5 and the MCP Bridge: Let Claude Actually Run Your PHP Code

Tinkerwell 5 ships an MCP server that gives Claude and Cursor direct PHP execution in your project context. Here's how to wire it up and use it well.

tinkerwell php claude-code mcp laravel developer-tools ai workflow
Featured image for "Tinkerwell 5 and the MCP Bridge: Let Claude Actually Run Your PHP Code"

If you have spent any time with Claude Code or Cursor lately, you already know the limitation that quietly breaks the magic: AI assistants are brilliant at suggesting PHP code, but they can’t run it. They reason about your application, but they can’t touch it. They write queries against your Eloquent models without knowing what your actual database contains. Tinkerwell 5 changes this equation in a surprisingly clean way, through a built-in MCP (Model Context Protocol) server that hands your AI assistant a direct execution environment inside your real project.

Tinkerwell has been a staple in the PHP toolkit for years. If you are not familiar with it, the short version: it is a GUI REPL for PHP that boots into your application context. You can run Eloquent queries, fire events, test service container bindings, preview Mailables, and trace through business logic, all without touching a controller or writing a test. Think of it as php artisan tinker with a proper editor, rich output formatting, SSH remote support, Docker integration, and a visual interface that shows you results as structured cards rather than raw CLI output.

Version 5, released under the banner “Welcome to the AI age,” makes the tool considerably more interesting for anyone building with AI assistance in 2026.

The MCP Server: What It Actually Does

The headline feature of Tinkerwell 5 is an MCP server that runs locally and exposes Tinkerwell’s execution capabilities to compatible AI tools. The server doesn’t require an API token. It exists solely to give AI assistants a way to run code inside the project Tinkerwell already has open.

Once configured, your AI assistant gains access to five MCP tools:

ToolWhat it does
evaluate-local-php-codeRun PHP in the currently open local project
evaluate-remote-php-codeRun PHP on a connected SSH server
get-remote-connectionsList available SSH connections
get-snippetsRead saved snippets from the current project
add-snippetSave new snippets back to the project

The critical detail is that both execution tools run PHP within your project’s application context. When Claude asks Tinkerwell to run:

User::where('active', true)->count()

It is running that query against your actual database, through your actual Eloquent model, with your real service providers booted. This is not a sandbox simulation. It is your application.

For debugging sessions, this changes the dynamic significantly. Instead of Claude suggesting “try checking the user count,” it can check the user count and see the result itself. The feedback loop collapses from many exchanges into one.

Setting It Up

Configuration is a one-click operation. Open Tinkerwell, go to Settings > Intelligence, and select your AI tool. For Claude Desktop, it automatically writes the MCP client configuration and prompts you to restart. For Cursor, same process. For anything else, including Claude Code, you can copy the JSON configuration and wire it into your MCP client manually.

The JSON looks roughly like this:

{
  "mcpServers": {
    "tinkerwell": {
      "command": "/Applications/Tinkerwell.app/Contents/MacOS/tinkerwell",
      "args": ["--mcp-server"]
    }
  }
}

The server launches automatically when your AI tool starts and connects to whichever project Tinkerwell has active. Switch projects in Tinkerwell, and your AI assistant’s execution context switches with it.

Remote Execution Is the Real Win

Local PHP execution via AI is useful. Remote execution is where this becomes genuinely powerful. Tinkerwell’s SSH connection support carries through to the MCP server. If you have a connection to a staging or production server, your AI assistant can run code there too.

This means you can ask Claude to check the actual state of data on your staging environment, verify that a migration ran correctly, or inspect configuration values without dropping into an SSH terminal and running commands manually. You maintain the conversation context, and Claude does the actual verification.

The Tinkerwell team includes a sensible warning in their documentation: remote execution can perform real actions on real systems, so review code carefully before letting it run. This is especially true if you are connected to production. The MCP server does not add a confirmation layer; it executes what the AI asks it to execute.

The AI Chat Companion

Separate from the MCP server, Tinkerwell 5 adds a Conversational Mode sidebar that lets you discuss code with an AI assistant in context. You describe what you want, the assistant generates a PHP snippet, and you run it or refine it further.

This is distinct from the MCP server integration. The chat sidebar is about using AI to help write Tinkerwell snippets. The MCP server is about letting external AI tools use Tinkerwell as an execution runtime. They serve different workflows, but they share one important design choice: Tinkerwell only sends the code currently in the editor and any files you explicitly reference to the AI service. No automatic project scanning, no accidental credential exposure.

AI Code Completion

Tinkerwell 5 also ships an improved AI code completion that complements the existing language server. The language server handles functions, variables, and known objects: the stuff it can infer from your codebase. The AI completion layer handles the context-aware suggestions that require understanding intent: completing a query chain, suggesting the right relationship method, inferring what a half-written closure is trying to do.

The completion is opt-in on demand rather than always-on, which keeps it from being noisy during normal typing. Trigger it when you want it.

Bring Your Own AI

One practical detail that matters for teams: Tinkerwell 5’s AI features are not bundled with a subscription tier. You provide your own API key from OpenAI, Anthropic, or another supported provider in the settings, and Tinkerwell uses it. This means no additional per-seat subscription on top of Tinkerwell’s existing license model, and you use whatever model you already have access to.

What’s Changed in Recent Releases

Beyond the core AI features, the 5.x changelog has accumulated useful incremental improvements through mid-2026:

Strict Types Toggle (5.15.0, April 2026): You can enable declare(strict_types=1) across all your Tinkerwell sessions via a preferences toggle. Applies consistently across local, Docker, SSH, and Laravel Cloud connections. If your codebase enforces strict types and you have been bitten by inconsistencies in Tinkerwell sessions, this resolves it cleanly.

SSH Proxy Jump Support: Tinkerwell now reads ProxyJump directives from ~/.ssh/config and auto-imports them. If your infrastructure puts application servers behind a bastion host, you no longer need to set up manual tunnels before connecting.

Laravel 13 Sandbox: The built-in Laravel sandbox runs Laravel 13. If you use Tinkerwell’s sandbox mode for quick experiments without an existing project, it now matches the current framework version.

Custom Docker /tmp Directories: For Docker containers with read-only /tmp or non-root execution environments, you can now configure the temp directory Tinkerwell uses for code execution. This surfaces less often than the other features but matters significantly when it matters.

Practical Workflow

The most useful pattern I have found for the MCP integration is debugging Eloquent queries. Claude can reason about query logic well, but the actual result set depends on data. With the MCP server connected:

  1. Describe the bug or the query you are trying to understand in Claude
  2. Claude generates the Tinkerwell execution call and checks the result
  3. It refines based on what it sees, not what it assumes
  4. You get a corrected query with evidence, not a hypothesis

For Symfony developers, Tinkerwell works the same way against Symfony projects. It is not Laravel-exclusive. The MCP tools do not care what framework is underneath; they run PHP in whatever context Tinkerwell has loaded.

The combination of Tinkerwell 5’s MCP server with Claude Code’s ability to read your codebase and write files closes a loop that has been open since AI coding assistants arrived: AI can now see the code, run the code, and observe real results in one session. That is a meaningfully different capability than suggestion alone.

Sources