Issue with NeuronAI MCP Server Instantiation via MCPConnector

[robbielove]

Hey @ilvalerione ,

Hope you’ve been doing well!

We’ve recently kicked off some initial POC testing for NeuronAI and I’m working alongside @smartens80 on this project. I’ve hit a bit of a snag with getting MCP servers to properly instantiate when invoked via Neuron, and I’m hoping you might be able to shed some light on it.

✅ What’s working:

• Neuron works fine locally when using Ollama.
• I can manually run MCP servers (e.g., @modelcontextprotocol/server-everything) via Claude or directly from CLI.
• I’ve confirmed the MCP servers themselves run fine when executed manually.

❌ What’s not working:

• When configured in Neuron using McpConnector, the MCP servers do not appear to instantiate.
• I receive a 504 in the browser — it appears Neuron is waiting for the MCP server to start, but it never does.
• No logs are produced from the MCP servers, making this difficult to debug.
• I’ve tried various servers (server-everything, server-memory, etc.) — none start via Neuron.

🧪 What I’ve tried:

To gain some visibility into what’s happening during tool invocation, I’ve used a few debug workarounds:

protected function tools(): array
{
    return [
        // Audible checkpoint
        ...McpConnector::make([
            'command' => 'say',
            'args' => ['hello'],
        ])->tools(),

        // Wrapper script that logs a timestamp when a process spawns
        ...McpConnector::make([
            'command' => '/Users/robbielove/mcp-debug.sh',
            'args' => [],
        ])->tools(),

        // Audible endpoint (never reached)
        ...McpConnector::make([
            'command' => 'say',
            'args' => ['hello'],
        ])->tools(),
    ];
}

The above works as expected up to the point of trying to spawn the MCP server. The second “hello” never runs — and no timestamp log file is created in the wrapper script — which suggests the MCP server never launches.

Here’s an example of the direct (non-wrapper) config I attempted:

...McpConnector::make([
    'command' => '/opt/homebrew/bin/node',
    'args' => [
        '/opt/homebrew/lib/node_modules/@modelcontextprotocol/server-everything/dist/index.js',
    ],
])->tools(),

🔍 Debug insights:

• I looked into StdioTransport.php and suspect the problem may stem from PHP’s process handling (proc_open) and/or I/O stream management.
• Even when wrapping the node server with a shell script, stdin/stdout/stderr behavior seems to block the process or cause it to silently fail.
• When I manually execute the same shell script or node command in the terminal, it works perfectly.

📎 Questions:

• Are there any known limitations or quirks with McpConnector and how it spawns long-running processes like the MCP servers?
• Is there a recommended way to enable logging or visibility into what's happening when Neuron attempts to launch a tool process?
• Is there a particular environment variable or logging config I can enable to get more info from StdioTransport or the MCP runner?

Any help would be massively appreciated — happy to try out any fixes or diagnostic steps you suggest.

Thanks!
Robbie

[ilvalerione]

The command should be always npx for node packages.

As the example in the documentation shows you should run an npx command with the following arguments, for the node package passed as arguments as well.

...McpConnector::make([
    'command' => 'npx',
    'args' => ['-y', '@modelcontextprotocol/server-everything'],
])->tools()

The process I went through for this implementation was just to install @modelcontextprotocol/server-everything globally with npm on my machine.

In the example above if you ask the agent What tools do you have at your disposal? it will list the example tools available from the server-everything MCP server.

To monitor what the agent does internally, including tool calls, you can connect it to Inspector: https://docs.neuron-ai.dev/advanced/observability

[robbielove]

Hey @ilvalerione,

Thanks for confirming the npx approach. I tried installing @modelcontextprotocol/server-everything globally and invoking it exactly as you suggested:

...McpConnector::make([
    'command' => 'npx',
    'args' => [
        '-y',
        '@modelcontextprotocol/server-everything'
    ],
    'env' => [
        'PATH' => '/opt/homebrew/bin:/usr/bin:/bin',
        'NODE_PATH' => '/opt/homebrew/lib/node_modules',
    ],
])->tools(),

That does spawn the process—but any single MCP tool failure still aborts the entire agent and I get a 500 with:

MCP server process has terminated unexpectedly

even though all my other tools are perfectly fine. Here’s why this is a two-part blocker:

---

1️⃣ I can’t even get a single (useful) tool (e.g. the MySQL MCP server) to work consistently

• It runs fine in Claude and via manual CLI, but when I plug it into Neuron via McpConnector, it never actually connects.
• I see the same “terminated unexpectedly” exception in my Laravel logs and Inspector, but no stdout/stderr, so I can’t learn why it died.
• I’d love for you to demonstrate a working mcpmysql setup on macOS (blank password), because if you can, I know it’s something in my wiring; if you can’t, then we’ve uncovered a deeper issue.
• I have tried multiple different mysql mcp servers (https://github.com/benborla/mcp-server-mysql, https://github.com/designcomputer/mysql_mcp_server) (There is an issue with the ben borla one with blank passwords but I have bypassed this by setting a password on my local mysql server)

eg.:

            ...McpConnector::make([
                'command' => 'npx',
                'args' => [
                    '-y',
                    '@smithery/cli',
                    'run',
                    'mysql-mcp-server',
                    '--verbose',
                ],
                'env' => [
                    'MYSQL_HOST' => 'host.docker.internal',
                    'MYSQL_PORT' => config('database.connections.crm.port'),
                    'MYSQL_USER' => config('database.connections.crm.username'),
                    'MYSQL_PASSWORD' => config('database.connections.crm.password'),
                    'MYSQL_DATABASE' => config('database.connections.crm.database'),
                    'PATH' => '/opt/homebrew/bin:/usr/bin:/bin',
                    'NODE_PATH' => '/opt/homebrew/lib/node_modules',
                ],
            ])->tools(),

---

2️⃣ The agent’s all-or-nothing loading model is a UX killer

• In a multi-tool agent (say you have 10 tools), one flaky tool nukes the whole agent, even if the others are 100% fine.
• I’d expect one of two behaviors:
  1. Optional vs. critical tools — if a tool is marked optional, it logs an error but the agent continues without it; if marked critical, the agent fails to start.
  2. Partial load — by default, load as many tools as possible; log failures and keep going.

Without at least one of those, every time I add a new MCP tool I’m going to end up spending hours restarting, hunting for missing logs, and so on.

---

What I need right now

1. Better Visibility: some way to capture the MCP subprocess’s stdout/stderr (dump, log, Inspector, whatever) so I can debug why it failed.
2. Graceful degradation: a flag or behaviour where the agent boots up with all working tools, and logs which ones failed.

My goal here is:

1. Get mcpmysql working end-to-end in Neuron (like it does in Claude).
2. Gain at least minimal logging of the subprocess.
3. Have the agent survive non-critical tool failures (e.g., start without that tool).

Happy to help test whatever change or setting you suggest.

Thanks, Robbie

[ilvalerione]

You can try this configuration:

...McpConnector::make([
    'command' => 'npx',
    'args' => [
        '-y',
        'mysql-mcp-server',
    ],
    'env' => [
        'MYSQL_HOST' => 'host.docker.internal',
        'MYSQL_PORT' => config('database.connections.crm.port'),
        'MYSQL_USER' => config('database.connections.crm.username'),
        'MYSQL_PASSWORD' => config('database.connections.crm.password'),
        'MYSQL_DATABASE' => config('database.connections.crm.database'),
        'PATH' => '/opt/homebrew/bin:/usr/bin:/bin',
        'NODE_PATH' => '/opt/homebrew/lib/node_modules',
    ],
])->tools(),

Let me know if it changes the behavior.

[robbielove]

Hi @ilvalerione,

Using the configuration you provided, I was able to connect to the MySQL MCP server successfully—thank you for that.

However, I've now moved on to integrating other MCP servers into my agent and have run into a few blockers—particularly with the GitHub MCP server.

---

❓ Key Question: Are non-NPX-based MCP servers supported?

From what I can tell, the MCP GitHub page lists a variety of servers—some use npx, some use Docker, and others need to be built manually.

The Neuron documentation only shows how to integrate npx-based MCP servers, but it's unclear whether non-npx ones are officially supported. I really need clarification here—is Neuron intended to support MCP servers launched via Docker or custom binaries as well?

---

🧪 My Attempt: Using Docker-based GitHub MCP

I tried to integrate the GitHub MCP server using Docker with the following config:

...McpConnector::make([
    'command' => 'docker',
    'args' => [
        'run',
        '-i',
        '--rm',
        '-e',
        'GITHUB_PERSONAL_ACCESS_TOKEN',
        'ghcr.io/github/github-mcp-server',
    ],
    'env' => [
        'GITHUB_PERSONAL_ACCESS_TOKEN' => config('services.github.token'),
    ],
])->tools(),

This config mirrors the command that works perfectly in my terminal:

docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN="your-token-here" ghcr.io/github/github-mcp-server
# Output: GitHub MCP Server running on stdio

Yet, in Neuron, the result is simply:

MCP server process has terminated unexpectedly

---

🔍 Where I'm Stuck

1. The server works outside Neuron: Running that Docker command manually starts the GitHub MCP server with no issues.
2. Neuron doesn't give me enough to debug: The “terminated unexpectedly” error is slightly more useful than a 500, but I still have no insight into why the process is failing or what it’s outputting.
3. No visibility into stdout/stderr: I can't tell whether Docker is failing, the image can't be pulled, an env var is missing, or something else entirely.

---

🙏 What I Need

1. Clarification: Does Neuron support MCP servers launched via Docker or custom binaries—or is npx the only supported integration path?
2. Better error visibility: How can I log or capture the MCP server’s stdout/stderr inside Neuron so I can debug failures like this?
3. Example: If non-npx servers are supported, could you provide a working example of one (e.g. using Docker)?

Really appreciate your help on this—I'm eager to get the GitHub tool integrated but I’m blocked until I know how to properly run it in Neuron.

Thanks,
Robbie

[ilvalerione]

Hi @robbielove thank you for all the details!
MCP is a protocol, so the direction is to support the protocol. We shouldn't care about docker or npx, since it is a protocol it should work as it is.

It can absolutely be a failure on the neuron client, but with MCP it's hard to debug because often the server log can provide the necessary details, but MCP server are often used like black boxes.

I will take a look to improve the feedback in case of the error, if you find a way to investigate on the MCP server side it could be great to have addition details.

[accountstam]

I created stdio server using 'https://mcp.so/server/server/php-mcp' package, couldn't use it with the native code:

protected function tools(): array {

			$tools = [
				...McpConnector::make([
					'command' => '/usr/sbin/php',
					'args'    => [
						__DIR__.'/mcp.test.php',
					],
					'env'     => [
						'apiToken' => self::tool_token,
					],
				])->tools(),
			];
			return $tools;
}

I created a workaround on McpClient class

public function __construct(array $config) {
            if(\array_key_exists('command', $config)) {
                $this->transport = new StdioTransport($config);
                $this->transport->connect();
                if(method_exists($this, 'initialize')) {
                    $this->initialize();
                }
            } else {
                // todo: implement support for SSE with URL config property
                throw new \Exception('Transport not supported!');
            }
        }

        protected function initialize() {
            $request = [
                "jsonrpc" => "2.0",
                "id"      => "neuron-req-".(++$this->requestId),
                "method"  => "initialize",
                "params"  => [
                    'protocolVersion' => '2024-11-05',
                    'capabilities'    => (object)[
                        'sampling' => new \stdClass(),
                    ],
                    'clientInfo'      => (object)[
                        'name'    => 'neuron-ai',
                        'version' => '1.0.0',
                    ],
                ],
            ];
            $this->transport->send($request);
            $this->transport->receive();
            $request = [
                "jsonrpc" => "2.0",
                "method"  => "notifications/initialized",
            ];
            $this->transport->send($request);
        }

added initialize function and use it, everything works now.
don't have a clue if it's the right place or even if it's needed, for php-mcp server it's needed.

[ilvalerione]

ok, I identify the problem. Let me fix it.

[accountstam]

@ilvalerione is there a way to chat with you in realtime? (telegram, slack...), I might be able to help with tools, I decided to use neuron for all future agent development, let me know.

Thanks!

[ilvalerione]

Fixed in 1.12.8

[accountstam]

@ilvalerione, Yep fixed!

Thanks mate!

[ilvalerione]

@accountstam if you have an Inspector account drop in a live chat, or feel free to send a PR.

[accountstam]

upgraded from version 1.10.20 to the latest and mcp for php is broken, any insight into it?

[ilvalerione]

any context about the error? What do you mean with "is broken"?

[accountstam]

The tool is loaded and exit immediately, something weird, didn't debug it - just downgraded.

[ilvalerione]

What MCP server are you trying to use? What is its configuration eventually?

[accountstam]

https://mcp.so/server/server/php-mcp

[ilvalerione]

Can you confirm you are using v3? Because I have a working example with v2 of the php-mcp server.