Skip to main content
This guide covers how to connect AI agents to the ShingleAI MCP server, including direct SSE connections, using the mcp-remote proxy, and troubleshooting common issues.

​
Connection URL

The MCP server is available at: 
https://mcp.shingleai.com

​
SSE Connection (Primary)

The MCP server uses Server-Sent Events (SSE) as its primary transport. SSE provides real-time, bidirectional communication over HTTP.

​
Connection Flow

  1. Establish Connection - Send a GET request to /sse with your MCP key
  2. Receive Endpoint - The server responds with a message endpoint URL
  3. Send Messages - POST JSON-RPC messages to the provided endpoint
  4. Receive Responses - Responses stream back through the SSE connection

​
Step 1: Establish Connection

curl -N https://mcp.shingleai.com/sse \
  -H "Authorization: Bearer mcp_live_abc123..."
The server responds with an SSE event containing the message endpoint: 
event: endpoint
data: /sse/message?sessionId=abc123-def456

​
Step 2: Send Messages

POST JSON-RPC messages to the endpoint you received: 
curl -X POST "https://mcp.shingleai.com/sse/message?sessionId=abc123-def456" \
  -H "Authorization: Bearer mcp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

​
Step 3: Receive Responses

Responses arrive through your SSE connection as message events: 
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}

​
Streamable HTTP (Alternative)

For clients that prefer a simpler transport, the MCP server also supports Streamable HTTP at the root endpoint. 
curl -X POST https://mcp.shingleai.com/ \
  -H "Authorization: Bearer mcp_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
For subsequent requests, include the session ID from the response: 
curl -X POST https://mcp.shingleai.com/ \
  -H "Authorization: Bearer mcp_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: abc123-def456" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", ...}'

​
Using mcp-remote (Claude Desktop)

Claude Desktop and some other MCP clients don’t support SSE natively. Use the mcp-remote package to bridge the connection.

​
Installation

npm install -g mcp-remote

​
Claude Desktop Configuration

Add the following to your Claude Desktop configuration file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json 
{
    "mcpServers": {
        "shingleai": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.shingleai.com/sse"
            ],
            "env": {
                "MCP_HEADERS": "Authorization: Bearer mcp_live_abc123..."
            }
        }
    }
}
Store your MCP key securely. Consider using environment variables instead of hardcoding the key in the configuration file.

​
Using Environment Variables

For better security, reference an environment variable: 
{
    "mcpServers": {
        "shingleai": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.shingleai.com/sse"
            ],
            "env": {
                "MCP_HEADERS": "Authorization: Bearer ${SHINGLEAI_MCP_KEY}"
            }
        }
    }
}
Then set the environment variable in your shell profile: 
export SHINGLEAI_MCP_KEY=mcp_live_abc123...

​
Health Check

Verify the MCP server is available before connecting: 
curl https://mcp.shingleai.com/health
Response: 
{"status": "ok"}
The health check endpoint doesn’t require authentication. Use it to verify connectivity before attempting to establish an authenticated connection.

​
Troubleshooting

Possible causes:
  • Network connectivity issues
  • Firewall blocking outbound HTTPS
  • Incorrect URL
Solutions:
  1. Verify network connectivity: curl https://mcp.shingleai.com/health
  2. Check firewall rules allow outbound HTTPS (port 443)
  3. Ensure you’re using https:// not http://
Possible causes:
  • Missing Authorization header
  • Invalid MCP key
  • Expired MCP key
  • Malformed Bearer token
Solutions:
  1. Verify your MCP key is correct
  2. Check the Authorization header format: Authorization: Bearer <key>
  3. Create a new MCP key if the current one may be expired or revoked
Possible causes:
  • Insufficient permissions for requested tool
  • Monthly call limit exceeded
  • Account suspended
Solutions:
  1. Check the error message for details
  2. Verify your MCP key has the required permissions
  3. Check your usage in the dashboard
  4. Upgrade your plan if you’ve hit the monthly limit
Possible causes:
  • Too many requests in a short period
  • Exceeding 100 requests per minute
Solutions:
  1. Implement request queuing or throttling
  2. Use exponential backoff when retrying
  3. Wait for the retryAfter duration before retrying
Possible causes:
  • Network instability
  • Idle timeout
  • Server maintenance
Solutions:
  1. Implement automatic reconnection logic
  2. Send periodic ping messages to keep the connection alive
  3. Check status.shingleai.com for service issues
Possible causes:
  • Incorrect configuration path
  • Environment variable not set
  • npx not found
Solutions:
  1. Verify the configuration file path for your OS
  2. Restart Claude Desktop after configuration changes
  3. Ensure Node.js and npm are installed and in your PATH
  4. Try running npx mcp-remote --version to verify installation

​
Session Management

MCP connections are stateful. Each connection receives a unique session ID that persists for the duration of the connection.
  • Session IDs are generated automatically on connection
  • Sessions expire after extended idle periods
  • Reconnections create new sessions - previous session state is not preserved
Design your agent to be stateless where possible. Don’t rely on server-side session state persisting between tool calls.

​
Next Steps

Available Tools

Explore the complete list of MCP tools

Integrations

See examples of MCP integrations