A quick start guide to testing Model Context Protocol (MCP) servers over HTTP using cURL.
Prerequisites
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 |