What is MCP

Model Context Protocol (MCP) is the bridge that allows Claude Code to connect external tools and services.

It supports two transport modes:

• stdio — standard input/output, good for local development

• sse — Server-Sent Events, used for remote or networked access

Most MCP connection issues aren’t caused by code, but by infrastructure details: HTTP protocol quirks, nginx defaults, or strict schema validation recently introduced by Anthropic.

Common Symptoms

Running:

claude mcp list

returns:

infonux: https://example.com/mcp_server (HTTP) - ✗ Failed to connect

Logs show:

[Error] Does not adhere to MCP server configuration schema

Meanwhile:

• nginx responds correctly

• curl returns valid SSE events

• HTTPS and tokens work normally

If all that is true, the issue isn’t networking — it’s configuration and protocol compatibility.

Why HTTPS Sometimes Breaks Everything

SSE only works over HTTP/1.1.

HTTP/2 uses multiplexing, which interrupts persistent streams.

When that happens, MCP CLI can’t maintain the connection and shows:

✗ Failed to connect

Quick summary:

SSE and Anthropic’s Shift to WebSocket

In spring 2025, Anthropic began phasing out the classic HTTP + Server-Sent Events (SSE) transport in favor of new mechanisms:

• Streamable HTTP, still MCP-compatible and supporting bidirectional traffic;

• WebSocket, which provides a more stable, persistent, and transport-independent connection.

The updated MCP specification (March 2025) introduced:

• full JSON-RPC bidirectional support,

• compatibility with standard HTTP servers (no extra SSE endpoint required),

• fewer dependencies on proxy/CDN quirks,

• no need to maintain two simultaneous channels.

SSE remains temporarily supported but is now officially deprecated.

Future SDKs (starting with 2025 releases) use WebSocket as the default transport, with Streamable HTTP available for backward compatibility.

Minimal Working MCP Configuration

Incorrect:

{
  "type": "sse",
  "command": "http://localhost:3010",
  "args": [],
  "env": {},
  "headers": { "Authorization": "Bearer TOKEN" }
}

Correct:

{
  "type": "sse",
  "url": "http://localhost:3010",
  "headers": { "Authorization": "Bearer TOKEN" }
}

Key differences:

• url replaces command

• args and env are removed

• headers are optional

Anthropic now enforces strict JSON schema validation — if the structure doesn’t match, MCP simply refuses to connect.

nginx Configuration for HTTPS and SSE

HTTPS works perfectly if the server is configured correctly for SSE.

The essentials: use HTTP/1.1, enable IPv6, and extend timeouts.

Minimal example:

server {
    listen 8443 ssl;           # HTTP/1.1 only, no http2
    listen [::]:8443 ssl;      # IPv6 required

    ssl_certificate     /etc/letsencrypt/live/your-domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain/privkey.pem;

    location / {
        proxy_pass http://localhost:3020/;
        proxy_http_version 1.1;       # required
        proxy_set_header Connection "";
        proxy_buffering off;          # must be disabled for SSE
        proxy_read_timeout 86400;     # long-lived connection
    }
}

Avoid:

listen 443 ssl http2;     # breaks SSE
proxy_buffering on;       # interrupts the stream
listen 8443 ssl;          # missing IPv6 — Claude Code won't connect

Connection Testing

Test the SSE stream manually:

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer TOKEN" \
  https://your-domain.com:8443/sse

Expected output:

event: endpoint
data: /messages?sessionId=template-xxx

If that works, check via CLI:

claude mcp list

Result:

✓ Connected

Security and Alternatives

If exposing a public port isn’t ideal:

ssh -L 3020:localhost:3020 user@your-server.com -N &

Then connect locally:

claude mcp add my-server \
  http://localhost:3020/sse \
  --transport sse \
  --header "Authorization: Bearer TOKEN"

Recommendations:

• never use HTTP in production

• rotate tokens regularly

• monitor logs for unusual activity

• use VPN or SSH tunnels for private setups

Summary

1. HTTPS works if:

   • you use HTTP/1.1,

   • IPv6 is enabled,

   • buffering is disabled,

   • timeouts are long enough.

2. HTTP/2 is incompatible with SSE.

3. Anthropic is migrating from SSE to WebSocket and Streamable HTTP.

4. “Failed to connect” errors usually mean configuration issues, not network problems.

5. curl remains the most reliable diagnostic tool.

Conclusion

MCP runs reliably over HTTPS — as long as the server doesn’t interfere with the SSE stream.

Anthropic’s move to WebSocket simplifies the protocol, improves stability, and aligns with modern real-time AI communication standards.

Stick to HTTP/1.1, follow the schema, and configure nginx carefully — the rest will just work.

Further Reading

• Official MCP Documentation

• MCP SDK (TypeScript)

• Anthropic Claude Code Docs

• Server-Sent Events vs WebSocket – MDN Overview

• nginx Proxying and HTTP/2 Limitations

Full nginx configuration and MCP Server Template:

github.com/modelcontextprotocol/typescript-sdk

Password reset link includes an extra path
The URL contains an unnecessary /admin segment after the main domain, e.g.:
http://magento.local/admin/admin_123456/admin/auth/resetpassword/key/xxxxxxxxxx/?id=1&token=yyyyyyyy
Solution: Apply the patch suggested in this comment.
Note: This issue exists in Magento 2.4.6 but has been fixed in version 2.4.7.

Missing password reset form
This issue is documented here. After upgrading Magento, the form might disappear, even with all custom modules disabled. A patch is needed to resolve this

diff --git a/view/adminhtml/layout/adminhtml_auth_resetpassword.xml b/view/adminhtml/layout/adminhtml_auth_resetpassword.xml
index 3ee2rd..8349152 111644
--- a/view/adminhtml/layout/adminhtml_auth_resetpassword.xml    2024-10-16 23:10:32.714755233 +0200
+++ b/view/adminhtml/layout/adminhtml_auth_resetpassword.xml    2024-10-16 23:11:13.808563121 +0200

@@ -9,7 +9,7 @@
     <update handle="admin_login" />
     <body>
         <referenceContainer name="login.content">
-            <block class="Magento\Backend\Block\Template" name="content" template="Magento_User::admin/resetforgottenpassword.phtml" />
+            <block class="Magento\Backend\Block\Template" name="content.reset.password" template="Magento_User::admin/resetforgottenpassword.phtml" />
         </referenceContainer>
     </body>
 </page>

Add this into composer.json:

"extra": {
    "magento-force": "override",
    "composer-exit-on-patch-failure": true,
    "patches": {
        "magento/module-user": {
             "Reset password form for admin": "patches/composer/admin_password_reset_form.patch",
        }
    }
},

Expired password reset link
Modifying the form block leads to the error: "Your password reset link has expired." This occurs because the token is not added to the form.

Another patch is required to fix this issue.

--- /dev/null
+++ ../Controller/Adminhtml/Auth/ResetPassword.php
@@ -24,7 +24,7 @@

             $this->_view->loadLayout();

-            $content = $this->_view->getLayout()->getBlock('content');
+            $content = $this->_view->getLayout()->getBlock('content.reset.password');
             if ($content) {
                 $content->setData('user_id', $userId)->setData('reset_password_link_token', $passwordResetToken);

"extra": {
    "magento-force": "override",
    "composer-exit-on-patch-failure": true,
    "patches": {
        "magento/module-user": {
            "fix admin post reset": "patches/composer/magento-module-user-controller-adminhtml-auth-resetpassword-php.patch"
        }
    }
},

Missing 'id' parameter
Sometimes the password reset link leads to an "expired link" message due to a missing id parameter in the file:
vendor/magento/module-user/view/adminhtml/templates/admin/resetforgottenpassword.phtml:

<form method="post" data-mage-init='{"form": {}, "validation": {}}'
      action="<?= $block->escapeUrl(
          $block->getUrl(
              '*/auth/resetpasswordpost',
              ['_query' => ['id' => $block->getUserId(), 'token' => $block->getResetPasswordLinkToken()]]
          )
      ) ?>" id="reset-password-form" autocomplete="off">

These issues require applying several patches to ensure the password recovery function works correctly in the Magento admin panel.