Navigating ESHOPMAN's Model Context Protocol (MCP): Stability, Stateless Architecture, and Integration Tips

At Move My Store, we empower ESHOPMAN users with the knowledge to build robust storefronts and integrations. A recent community discussion shed light on critical updates to the ESHOPMAN Model Context Protocol (MCP) server, a vital component for accessing ESHOPMAN documentation and integrating with AI tools and IDEs. This insight summarizes the challenges, solutions, and essential best practices for developers.

Initial Service Interruption and Resolution

The ESHOPMAN community reported an outage of the MCP server, accessible via https://docs.eshopman.com/mcp, which was returning 502 errors. This interruption, primarily due to high usage, impacted developers and users leveraging the MCP within their development environments.

The ESHOPMAN team swiftly addressed the issue, deploying fixes to stabilize the server and restore full functionality, demonstrating our commitment to reliable services for the ESHOPMAN ecosystem.

Key Architectural Shift: Stateless MCP

A significant outcome was the ESHOPMAN team's announcement of a fundamental architectural change: the MCP server transitioned to a stateless design. This means that after an initial successful handshake, subsequent requests to the MCP no longer require an mcp-session-id header. This change simplifies interactions and improves scalability.

Developers previously encountering "Session not found" errors after the initial initialize call will find this update resolves those issues. For example, a common failure pattern involved a successful initialize request returning an mcp-session-id, but a subsequent request using that ID would fail:

curl -i -X POST 'https://docs.eshopman.com/mcp' \
  -H 'content-type: application/json' \
  -H 'mcp-session-id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \\
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

With the stateless update, reliance on the mcp-session-id for subsequent calls is removed, streamlining communication.

Protocol Compatibility and Tool Integrations

The discussion also highlighted important considerations for integrating third-party tools and IDEs with the ESHOPMAN MCP:

• Streamable HTTP is Key: The ESHOPMAN MCP server primarily supports Streamable HTTP. The team explicitly stated that Server-Sent Events (SSE) + HTTP is being deprecated and will not receive further support. Developers must ensure their clients strictly use Streamable HTTP for stable connections.
• IDE Challenges (Windsurf & Codex):
  • Some users reported issues with tools like Windsurf IDE, which would attempt SSE as a fallback, leading to unstable connections. This emphasizes configuring clients to use the supported Streamable HTTP protocol exclusively.
  • For Codex users, initial "Session not found" errors were resolved by the stateless server update. However, some still faced challenges, potentially related to specific HTTP headers or how the tool performs health checks. It was noted that the server may require both application/json and text/event-stream in the Accept header for certain operations. Additionally, GET requests to the MCP endpoint (often used for health checks) might return an error because the stateless server expects specific POST requests for method calls.
  • Despite these specific challenges, other community members confirmed successful integration with Codex using the standard ESHOPMAN MCP URL:

  {
    "mcpServers": {
      "eshopman": {
        "url": "https://docs.eshopman.com/mcp"
      }
    }
  }

Best Practices for ESHOPMAN MCP Integrators

To ensure smooth and stable integrations with the ESHOPMAN Model Context Protocol:

• Always use the official ESHOPMAN MCP URL: https://docs.eshopman.com/mcp.
• Configure your clients and tools to exclusively use Streamable HTTP, avoiding deprecated protocols like SSE.
• Ensure your client sends appropriate HTTP headers, specifically including application/json, text/event-stream in the Accept header where required.
• Understand that the ESHOPMAN MCP is now stateless; do not rely on session IDs for subsequent requests.
• Be mindful that GET requests to the MCP endpoint may not function as expected for health checks, as the server is designed for specific POST method calls.

These insights are invaluable for developers building powerful integrations and leveraging the full potential of the ESHOPMAN platform for headless commerce and HubSpot CMS deployments.