Testing MCP Servers with cURL

A quick start guide to testing Model Context Protocol (MCP) servers over HTTP using cURL.

Prerequisites

cURL installed
An MCP server endpoint URL
Authentication token (if required)

Setup

First, set your environment variables:

# Set your MCP endpoint and auth token
MCP_ENDPOINT="https://glama.ai/endpoints/xxx/mcp"
MCP_TOKEN="mcp_k1.xxx.xxx"

Step 1: Initialize a Session

Streamable HTTP uses stateful sessions. You must initialize a session first to get a valid Mcp-Session-Id.

# Initialize session and capture the session ID from response headers
response=$(curl -s -D - -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-test",
        "version": "1.0.0"
      }
    },
    "id": 1
  }' \
  "$MCP_ENDPOINT")

# Extract session ID from headers (case-insensitive)
SESSION_ID=$(echo "$response" | grep -i "mcp-session-id" | cut -d' ' -f2 | tr -d '\r')

echo "Session ID: $SESSION_ID"

Step 2: Send the Initialization Confirmation

After receiving the initialize response, send a notification to confirm:

curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }' \
  "$MCP_ENDPOINT"

Step 3: List Available Tools

Now you can interact with the MCP server:

curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }' \
  "$MCP_ENDPOINT"

Step 4: Call a Tool

Replace your_tool_name with an actual tool from the tools/list response:

curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "your_tool_name",
      "arguments": {
        "param1": "value1"
      }
    },
    "id": 3
  }' \
  "$MCP_ENDPOINT"

Step 5: Terminate Session

When done, clean up the session:

curl -s -X DELETE \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  "$MCP_ENDPOINT"

Complete Test Script

Here's a reusable script you can save as test-mcp.sh:

#!/bin/bash
set -e

# Configuration
MCP_ENDPOINT="${MCP_ENDPOINT:?Please set MCP_ENDPOINT}"
MCP_TOKEN="${MCP_TOKEN:?Please set MCP_TOKEN}"

echo "=== MCP Streamable HTTP Test ==="
echo ""

# Step 1: Initialize
echo "1. Initializing session..."
response=$(curl -s -D - -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "1.0.0"}
    },
    "id": 1
  }' \
  "$MCP_ENDPOINT")

SESSION_ID=$(echo "$response" | grep -i "mcp-session-id" | cut -d' ' -f2 | tr -d '\r')

if [ -z "$SESSION_ID" ]; then
  echo "ERROR: Failed to get session ID"
  echo "$response"
  exit 1
fi

echo "Session ID: $SESSION_ID"
echo ""

# Step 2: Send initialized notification
echo "2. Sending initialized notification..."
curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}' \
  "$MCP_ENDPOINT"
echo ""

# Step 3: List tools
echo "3. Listing tools..."
curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' \
  "$MCP_ENDPOINT"
echo ""

# Step 4: List resources
echo "4. Listing resources..."
curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "resources/list", "id": 3}' \
  "$MCP_ENDPOINT"
echo ""

# Step 5: List prompts
echo "5. Listing prompts..."
curl -s -X POST \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "prompts/list", "id": 4}' \
  "$MCP_ENDPOINT"
echo ""

# Cleanup
echo "6. Terminating session..."
curl -s -X DELETE \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  "$MCP_ENDPOINT"

echo ""
echo "=== Test Complete ==="

Usage:

chmod +x test-mcp.sh

# Set environment variables and run
MCP_ENDPOINT="https://glama.ai/endpoints/xxx/mcp" \
MCP_TOKEN="mcp_k1.xxx.xxx" \
./test-mcp.sh

Common Errors and Solutions

Error	Cause	Solution
`{"error":"No sessionId"}`	Missing `Mcp-Session-Id` header	Initialize first to get a session ID, then include it in all requests
`{"error":"No active transport"}`	Invalid or expired session ID	You cannot make up a session ID. Use the real one from the `initialize` response
Request "hangs" with no output	Normal SSE behavior on GET	GET requests open a long-lived stream. Use POST for immediate responses
`404 Not Found`	Session expired or terminated	Re-initialize to get a new session ID
`400 Bad Request`	Malformed JSON or missing required fields	Check your JSON-RPC message format

Quick Reference: HTTP Methods

Method	Purpose	Returns
POST	Send JSON-RPC requests (initialize, tools/list, tools/call, etc.)	Immediate JSON response
GET	Open SSE stream for server → client messages	Long-lived connection (waits for events)
DELETE	Terminate a session	Confirmation

JSON-RPC Methods Reference

Method	Description
`initialize`	Start a new session
`notifications/initialized`	Confirm initialization complete
`tools/list`	List available tools
`tools/call`	Execute a tool
`resources/list`	List available resources
`resources/read`	Read a resource
`prompts/list`	List available prompts
`prompts/get`	Get a prompt