Integrating with Cursor via Streamable HTTP

License: Apache-2.0  |  Version: 1.5.1  |  Go: 1.26+  |  Dependencies: Zero external runtime dependencies

Cursor supports MCP servers via Streamable HTTP transport. AegisGate MCP provides a full Streamable HTTP implementation with SSE streaming support and Mcp-Session-Id session management (MCP protocol 2025-06-18).

Prerequisites

Step 1: Start AegisGate MCP in HTTP Mode

./mcp-server --transport http --demo --addr :8081

The server now accepts MCP requests at http://localhost:8081/mcp.

With Authentication

./mcp-server --transport http --demo --addr :8081 --token my-secret-bearer

With TLS

./mcp-server --transport http --demo --addr :8081 \
  --tls --tls-cert server.pem --tls-key server.key

Step 2: Configure Cursor

Open Cursor Settings → MCP Servers → Add New MCP Server:

Or edit Cursor’s MCP configuration file:

{
  "mcpServers": {
    "aegisgate-mcp": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

With Authentication

{
  "mcpServers": {
    "aegisgate-mcp": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-bearer"
      }
    }
  }
}

Step 3: Verify the Connection

1. Restart Cursor
2. Open a new chat
3. The three demo tools (ping, system_info, echo) should appear as available MCP tools
4. Try: “Use the ping tool from aegisgate-mcp”

How Session Management Works

AegisGate MCP implements the Mcp-Session-Id header (MCP 2025-06-18 spec):

1. Initialize: Cursor sends initialize → server responds with Mcp-Session-Id: <256-bit ID> header
2. Subsequent requests: Cursor includes Mcp-Session-Id: <ID> in all following requests
3. Session expiry: Sessions expire after 30 minutes of inactivity
4. Session termination: Cursor sends DELETE /mcp with the session ID to terminate

This happens automatically — Cursor handles session IDs without manual configuration.

SSE Streaming

AegisGate MCP supports SSE responses. If Cursor sends Accept: text/event-stream, the server responds with:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","result":{...},"id":1}

If Cursor doesn’t request SSE, the server falls back to standard application/json responses. Both modes are fully supported.

Docker Deployment

docker pull ghcr.io/aegisgatesecurity/aegisgate-mcp:1.5.1
docker run -d --name aegisgate-mcp -p 8081:8081 \
  ghcr.io/aegisgatesecurity/aegisgate-mcp:1.5.1 \
  --transport http --demo --addr :8081

Then point Cursor at http://localhost:8081/mcp.

Troubleshooting

Connection refused

• Verify the server is running: curl http://localhost:8081/mcp -X POST -d '{}' -H "Content-Type: application/json"
• Check the port: lsof -i :8081
• Try a different port: --addr :9091

404 Not Found

• Ensure you’re hitting /mcp not the root: http://localhost:8081/mcp
• Verify the server is in HTTP mode (not TCP or stdio)

Authentication failed (-32001)

• The --token value must match the Authorization: Bearer header exactly
• Check for trailing whitespace in the token

Session expired (404)

• Sessions expire after 30 minutes of inactivity
• Cursor will automatically re-initialize a new session