MCP Intro

This guide covers the steps and solutions discussed for integrating a local MCP server with Cursor, and fixing some common issues with the SSE (/sse) and message handling (/messages).

Overview of SSE and MCP Communication

1. MCP Server and SSE:

Server-Sent Events (SSE) is a protocol where the server pushes updates to the client over a single, long-lived HTTP connection. The MCP server uses SSE for real-time communication with clients like Cursor.

2. Endpoints in MCP Communication:

The MCP server communicates with the client using two key endpoints:

  • /sse: The client initially connects to this endpoint to establish the SSE connection. This is where the server sends events like endpoint or other messages during the session.

  • /messages: Once the client receives the endpoint event, it sends subsequent messages (like JSON-RPC) to this endpoint.

Step-by-Step Communication Flow:

  1. Client Connects to /sse:

    • The client (Cursor) sends an HTTP request to the server’s /sse endpoint to start the SSE stream.

    • Request Example:

      GET https://yourserver.com/sse

  2. Server Sends the endpoint Event:

    • Upon establishing the SSE connection, the server responds by sending an endpoint event.

    • This event tells the client where future messages should be sent (usually to /messages).

    • SSE Response Example:

      event: endpoint
data: {"url": "/messages/"}

  3. Client Sends Messages to /messages:

    • Once the client has received the endpoint event, it begins sending messages to the /messages endpoint, which could include any JSON-RPC or other communication the client needs to process.

    • Example of a POST Request to /messages:

      POST https://yourserver.com/messages
{
  "jsonrpc": "2.0",
  "method": "some_method",
  "params": {},
  "id": 1
}

  4. Server Responds via SSE:

    • After processing the message, the server sends a response or another event (like message) to the client via the SSE connection. This might contain data or a result from

Step-by-Step Communication Flow -- but even more detail:

This is the debug log from my MCP server:

Here's a step-by-step breakdown of the MCP interaction shown in the logs: https://www.perplexity.ai/search/why-does-mcp-use-sse-over-http-8c9JHttgQEurb7jCJWtJ2g

1. SSE Connection Establishment

  • Client sends GET /sse to initiate SSE streaming

  • Server:

    • Creates new session (957ca12d-...)

    • Returns 200 OK with text/event-stream

    • Sends initial endpoint event with POST URL:

    • This tells the client where to send future requests[1]

2. Client Initialization

  • Client POSTs to /messages/?session_id=...:

  • Server responds via SSE:

    This negotiates protocol capabilities[1]

3. Notification Handling

  • Client sends notification (no response needed):

  • Server logs receipt but doesn't send SSE response[1]

4. Tool Listing Request

  • Client requests tool list:

  • Server responds via SSE:

    Demonstrates tool capability exposure[1]

Key Flow Pattern

Important Details

  • Session Persistence: Connection maintained through periodic ping events every 15 seconds[1]

  • JSON-RPC Structure:

    • id field links requests to responses

    • method specifies desired action

    • params contains input data

  • Error Handling: 405 Method Not Allowed when trying to POST to /sse endpoint[1]

  • Deprecation Notice: While this uses SSE, newer MCP implementations prefer Streamable HTTP as mentioned in previous answers[1]

PreviousGuardrailsNextMachine Learning Audio Classification

Last updated

Was this helpful?