Your MCP server is configured, but Claude Code cannot connect. Codex lists the server, yet the tool you need is missing. Or the connection succeeds, but a request returns “application unavailable.”

These symptoms point to different failures. Reinstalling packages or increasing timeouts before identifying the failing layer can leave you changing settings that were already correct.

The useful distinction is simple: did the client load the configuration, initialize the MCP connection, and reach the intended application or service? This guide follows that sequence, with separate checks for Claude Code and Codex, configuration examples, and ways to test the server independently.

On Vagon Cloud Computer, you can keep the assistant, MCP server, and production application in the same desktop environment. That reduces connections between separate machines and lets you inspect the application alongside the diagnostic results.

The command examples use PowerShell on Windows. WSL differences are explained where they affect executable paths, networking, or which environment a connection actually reaches.

Start with the Symptom, Not a Reinstall

First, capture the exact error and note when it appears: while the client starts, during authentication, when tools load, or after a tool call. That timing helps identify which part of the connection needs attention.

Then check the server’s transport. With stdio, the client launches a local process. With Streamable HTTP, it connects to a server endpoint. These require different troubleshooting steps, as the MCP transport specification explains.

Use this as a routing guide, not a definitive diagnosis. For example, missing tools may reflect an intentional filter rather than a broken server.

Source: Composio

Before editing the configuration, save a copy without sharing its credentials. Make one targeted change, repeat the same check, and record the result. If the failure moves from process startup to authentication, that is useful progress: the next layer is now reachable.

Start with the earliest failing stage. There is little value in troubleshooting application permissions when the server executable has not launched.

Check Which Computer and Runtime Are Making the Connection

Before changing a path or URL, locate the assistant process, the MCP server, and the application or service it accesses. A setup that works on your laptop will not automatically work inside a remote desktop, even if the configuration files look identical.

For a desktop application workflow, keeping these components together on Vagon Cloud Computer reduces the number of machine boundaries involved. Your personal device displays the desktop; the assistant and application run inside it.

However, if you launch Claude Code or Codex on your laptop, a local server command runs there. It does not start a process on the cloud computer.

Confirm What Localhost Refers To

An endpoint such as:

points to the loopback interface of the environment making the request. Test it from the environment running the MCP client.

Opening that address in your laptop’s browser does not test a server running inside the cloud desktop. Likewise, an OAuth flow that returns to a loopback callback must reach the environment where the client is listening.

Keep Windows and WSL Paths Separate

If the client runs in WSL, check its runtime and paths there. A Windows Node installation does not establish that the expected Linux executable is available.

These paths may refer to the same project files, but they belong to different command environments:

Networking also depends on configuration. Default WSL NAT networking and supported mirrored networking handle Windows-to-Linux access differently. Use Microsoft’s WSL networking guidance to check your actual arrangement rather than replacing localhost with a guessed IP address.

Once the execution environment is clear, continue with its launch command or HTTP endpoint.

Source: Microsoft Learn

If a Local Server Will Not Start, Check the Launch Command

For a stdio server, begin with the executable the client is supposed to launch. Check it from PowerShell inside the same Windows desktop:

These commands apply to a Node-based server. For Python or another runtime, inspect the executable named in that server’s installation instructions. A Python package installed in a virtual environment may require that environment’s interpreter.

Source: DevToolLab

If PowerShell finds the runtime but the desktop client does not, compare their environments. Restart the client after a recent installation or PATH change, or configure the verified absolute executable path.

Separate the Command from Its Arguments

The executable and its arguments are different configuration fields. For a locally installed Node server, the launch structure might be:

These are illustrative paths, not a package to install. Replace them with the actual runtime and the server’s documented entry point.

Test the equivalent command manually:

If the server depends on relative files, run it from its required working directory. Missing modules, invalid arguments, and inaccessible files should be investigated before changing client settings.

A server may remain quiet while waiting for MCP messages. That is normal for some implementations. Stop the process you launched manually before testing through the assistant, especially if the application bridge supports only one connection.

Look for Startup Prompts and Unexpected Output

Package runners may need an initial download, while some servers require credentials or a separate setup step. Complete the documented prerequisites so startup does not depend on an unanswered interactive prompt.

Also check where the server writes logs. The MCP transport specification reserves stdout for protocol messages and permits diagnostic logging on stderr. A banner or debug print sent to stdout can interfere with initialization.

Increase the startup timeout only when the launch command is valid and the process genuinely needs longer. A longer wait cannot repair a missing executable or malformed configuration.

Claude Code: Check Scope, Approval, and the Loaded Definition

Run these commands from the project directory where you normally start Claude Code:

Replace example with your server’s registered name. Check which definition loads, whether approval is pending, and what failure the client reports. Inside an interactive session, use /mcp to inspect the server and its available actions.

Source: wmedia.es

Compare the Definition with a Minimal Example

For the illustrative Node server from the previous section, a project-level .mcp.json could contain:

{
  "mcpServers": {
    "example": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "D:\\mcp\\example-server\\dist\\index.js"
      ]

{
  "mcpServers": {
    "example": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "D:\\mcp\\example-server\\dist\\index.js"
      ]

Replace both paths with verified locations. The doubled backslashes are JSON escaping; they do not represent doubled separators in the actual Windows path.

This example assumes the server needs no additional arguments or environment variables. Preserve any requirements documented by its maintainer, and do not replace an existing configuration containing other servers wholesale.

Check Scope Before Editing Another File

Claude Code supports local, project, and user MCP configuration scopes. Project definitions use .mcp.json; local and user definitions are stored in .claude.json with different scope placement.

If you edited a project file but launch Claude Code elsewhere, you may be checking a different setup. Duplicate server names across scopes can also make the loaded definition differ from the one you expected.

Project servers may require approval. Review that request in the interactive session rather than trying to bypass workspace trust.

Read the Startup Failure

For persistent errors, start a diagnostic session:

Follow Anthropic’s MCP debugging guidance to inspect startup output and discovery failures. Remove credentials before sharing logs.

If the server connects but expected tools remain absent, reconnect through /mcp and compare discovery results with the server’s documented capabilities. A working Claude Desktop connection is useful evidence, but it does not prove Claude Code uses the same configuration or environment.

Codex: Verify the Active Configuration and Tool Filters

Codex uses TOML rather than Claude Code’s JSON format. The same server can work with both clients, but each needs its own valid definition.

Start by checking the configured servers:

Inside the Codex terminal interface, enter /mcp to inspect active connections.

Compare the TOML Definition

Codex stores user configuration in ~/.codex/config.toml. Trusted projects can also use .codex/config.toml. Confirm which environment and configuration you are editing, particularly if you also run Codex inside WSL.

Source: Roam Developer Documentation

The same illustrative Node server from the Claude Code example could use:

[mcp_servers.example]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\mcp\example-server\dist\index.js']

[mcp_servers.example]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\mcp\example-server\dist\index.js']

Replace these paths with the actual installation locations. TOML’s single-quoted literal strings preserve Windows backslashes without the JSON escaping shown earlier.

The cwd field sets the server’s working directory. Use the directory required by the server, which may differ from the project folder where you launched Codex. Add the entry without replacing unrelated configuration.

Source: Roam Developer Documentation

Check Whether Tools Are Intentionally Restricted

Before treating missing tools as a server failure, inspect:

• enabled: setting it to false disables the server.

• enabled_tools: an allow list that limits available tools.

• disabled_tools: a deny list applied after the allow list.

Compare the loaded definition with the official Codex MCP configuration, then check whether the expected tool is actually exposed by the server.

Verify Authentication and Timeout Settings Separately

For an HTTP server that supports OAuth, use:

Replace example with its registered name. For bearer-token authentication, verify that the configured credential variable is available to the Codex process without printing its value.

Finally, startup_timeout_sec controls startup, while tool_timeout_sec controls tool execution. Both use seconds. Identify which stage fails before adjusting either setting.

HTTP Connection Failing? Check the Endpoint and Listening Process

For an HTTP server, verify the complete endpoint documented by its maintainer: scheme, hostname, port, and path. A service homepage or health-check route is not necessarily its MCP endpoint.

Also confirm the transport. Streamable HTTP and older HTTP+SSE configurations should not be swapped simply because both use URLs.

Source: Christian Posta

Identify What Is Listening

For a server expected to run inside the Windows desktop, test its configured address and port:

Replace the illustrative port with the actual one. If the connection succeeds, check which local process owns the listener:

Use the returned process ID to inspect it:

Replace 1234 with the actual OwningProcess value. Microsoft’s Get-NetTCPConnection documentation explains the connection properties.

A process named node or python is not enough to identify the intended server. Compare its launch details with your configuration. Do not terminate an unfamiliar process merely because it occupies the expected port.

These listener checks apply to local Windows processes. For a remote service, inspect its hosting environment or ask the server administrator.

Interpret the Next Failure

A successful TCP test does not verify authentication or MCP initialization. Use the client’s error details and server logs to narrow the next step:

• Connection refused: check the listener, address, and port.

• 401: check authentication requirements and credentials.

• 403: investigate authorization scopes, account access, or policy.

• 404: verify the endpoint path and proxy routing.

• Timeout: investigate reachability, proxy behavior, or a stalled server.

These are diagnostic clues, not definitive conclusions.

If OAuth returns to a loopback callback, confirm that the browser flow reaches the environment where the client is listening. For token-based access, check the credential source without displaying its value.

Source: Christian Posta

Investigate certificate and proxy errors directly. Disabling TLS verification, switching off the firewall, or exposing a local MCP endpoint publicly should not be the default fix.

Connected, but the Application Still Cannot Be Reached?

If the expected tools appear but return “application unavailable” or “no active project,” move beyond the client configuration. The MCP server may be working while its connection to the production application is not.

Many integrations use this chain:

Assistant → MCP server → application bridge or addon

The bridge might communicate through a socket, a shared directory, or an application-specific interface. Follow the integration’s documented design rather than assuming another network port must be opened.

Check the Application and Bridge Together

Open the target application inside Vagon Cloud Computer and load the intended project. Then verify:

• The required addon, extension, or plugin is installed and enabled.

• Any manual bridge-starting step has been completed.

• The server and bridge use matching connection settings.

• The installed versions are compatible.

• The bridge is attached to the intended application instance and user session.

For file-based bridges, check that both processes can access the same directory. A matching folder name does not help if one process resolves it somewhere else or lacks access.

Confirm the Target with a Read-Only Request

Choose an inspection tool the server actually exposes. A useful first request is:

Report the application version and active project name. Do not modify the project, save files, or start processing.

Compare the response with the application visible on the desktop. An unexpected project name can point to a duplicate application instance or a bridge attached to another session.

Where supported, computer use can help inspect a disabled addon or visible warning. It remains a separate access method. Confirm the MCP bridge itself through a successful tool response before asking it to make changes.

Isolate the Failure with MCP Inspector

When the client’s logs do not make the cause clear, test the server separately with MCP Inspector. It lets you inspect initialization, discover tools, and examine individual responses without relying on the assistant to choose an action.

From PowerShell inside the cloud desktop, run:

Follow the current runtime requirements and open the generated address in the browser inside that desktop. Keep the Inspector session token private.

Match the Connection Settings

Use the same transport, executable and arguments, or HTTP endpoint as the failing client. Match the required working directory and environment variables too. Inspector may need its own authentication flow; it does not automatically inherit the assistant’s credentials.

Source: DevToolLab

For stdio, Inspector launches a separate server process. If the application bridge allows only one client, disconnect the previous test before attaching another.

Check initialization first, then discovery. If tools are expected, confirm their names and call one documented read-only operation with valid inputs.

Source: DevToolLab

Use the Difference to Narrow the Search

If Inspector succeeds but Claude Code or Codex fails, compare the client-specific configuration, environment, authentication, and protocol behavior.

If both fail at the same stage, focus on their shared dependencies: the server, endpoint, runtime, or application bridge. This narrows the investigation without proving that every client behaves identically.

Record the failing stage, exact error, and settings needed to reproduce it. Remove credentials before sharing the result with the server maintainer or support team.

Keep the Working Setup Reproducible on Vagon

Once the connection works, save a short record of the setup rather than relying on terminal history.

Keep the client and server versions, verified launch command or endpoint, working directory, required environment variable names, and any application-bridge startup step. Store credentials separately, not in a shared troubleshooting note.

Include one successful read-only request and the result you expect. For an application integration, that might be the active project name. This gives you a quick check after an update or a new session.

Then test from a fresh client session. Confirm which dependencies start automatically and which need attention. A saved server definition does not mean its application bridge restarts with it.

Vagon Cloud Computer lets you keep the assistant, production applications, integration files, and test projects together in one desktop environment. You can return from another device without rebuilding that setup on your personal computer.

Start with one assistant, one server, and one verified task. Once that connection is repeatable, expand the workflow. Set up your next connected workflow on Vagon Cloud Computer with the tools you need to run it and inspect the result in the same workspace.

FAQs

Why does my MCP server work in a terminal but not in the desktop app?

The processes may use different executable paths, environment variables, or working directories. Compare the loaded configuration with the command you tested. Restart the client after relevant environment changes. A process staying open does not establish that MCP initialization succeeded.

Does localhost point to my laptop or my Vagon computer?

It refers to the environment making the connection. A client running inside Vagon uses that environment’s loopback interface, not your laptop’s. WSL adds a networking boundary whose behavior depends on its configured mode.

Can Claude Code and Codex use the same MCP server?

Yes, where the server supports both clients’ transport and protocol requirements. Configure each client separately. A stdio client normally launches its own server process, while an HTTP server may accept multiple connections. Application bridges can impose additional limits.

Why is the server connected but showing no tools?

Check its documented capabilities and the client’s tool filters, then inspect discovery errors. Some MCP servers provide resources or prompts rather than tools, so an empty tool list is not automatically a failure.

Should I increase the startup timeout?

Only when a valid launch command legitimately needs more startup time. Missing executables, malformed configuration, and authentication failures require different fixes. Also distinguish server startup from a tool call that times out after connecting.

Do I need to open a firewall port for stdio?

No. The MCP transport uses the subprocess’s input and output streams. The server may separately need network access to an API or application bridge, but that is a different connection.

Does a preinstalled application include its MCP integration?

Do not assume so. Application installation, server configuration, bridge activation, and authentication are separate checks. Verify the requirements of the integration you selected.

What should I send when asking for support?

Include the client and server versions, operating environment, transport, sanitized configuration, exact error, and failing stage. State whether MCP Inspector reproduces the issue. Remove credentials, session tokens, authorization headers, and sensitive project details before sharing logs.