Build with AI

Calling the server directly

MCP clients handle this for you. If you are writing the integration yourself, the streamable-http transport has three requirements that are easy to miss:

• Carry the session idinitialize returns an mcp-session-id response header — not a field in the body. Every later request must send it back, or the server answers 400 Missing session ID.
• Accept both content typesSend Accept: application/json, text/event-stream. Offering only one of the two is rejected with 406.
• Parse the SSE framesSuccessful replies come back as server-sent events, not a bare JSON document: each JSON-RPC message arrives as a data: line preceded by event: message. Decode the data: payloads rather than running JSON.parse over the whole body.

A complete exchange — handshake, tool call, and releasing the session:

MCP_URL="https://mcp.shipthis.ai/mcp"
API_KEY="YOUR_SHIPTHIS_API_KEY"
ORG="YOUR_ORG"

# 1. initialize — the session id arrives in the mcp-session-id response header
SID=$(curl -sS -D - -o /dev/null -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: $API_KEY" \
  -H "organisation: $ORG" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}' \
  | awk 'tolower($1)=="mcp-session-id:"{print $2}' | tr -d '\r')

# 2. confirm the handshake (a notification — no response body)
curl -sS -o /dev/null -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -H "x-api-key: $API_KEY" \
  -H "organisation: $ORG" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. call a tool — repeat the session id and auth headers on every request
curl -sS -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -H "x-api-key: $API_KEY" \
  -H "organisation: $ORG" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_location","arguments":{"query":"Rotterdam"}}}'

# 4. optional: release the session when you are done
curl -sS -X DELETE "$MCP_URL" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID"

Decoding the data: line of that tool call gives you the JSON-RPC result:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "..." }
    ],
    "isError": false
  }
}

Sessions are cheap to keep and cheap to drop. Reuse one across many calls rather than re-running initialize per request, and DELETE it when you are finished. The protocol version above (2024-11-05) is the one this portal uses to build its own tool catalogue.

Auth and errors

The server splits its failures into two shapes, and they do not look alike. Handling only one of them is the most common integration bug.

Auth failures return HTTP 200

A rejected tool call is still a successful HTTP request and still a well-formed JSON-RPC response. There is no error member — the failure is reported as result.isError, with the reason in the text content. Branch on isError; a status-code check alone will read this as success:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "Access denied: Authentication error occurred" }
    ],
    "isError": true
  }
}

Transport failures return a real status code

Problems the server hits before it reaches your tool — a missing session, an unacceptable Accept header — come back as plain JSON (no SSE framing) with a genuine 4xx status and a JSON-RPC error member:

{
  "jsonrpc": "2.0",
  "id": "server-error",
  "error": {
    "code": -32600,
    "message": "Bad Request: Missing session ID"
  }
}

What each failure means

A quick way to triage. tools/list needs no credentials. If it succeeds but your tool calls come back denied, the transport is fine and the problem is your x-api-key / organisation pair. If tools/list itself fails, the problem is the connection, not your credentials.

Limits and retries

ShipThis does not currently publish numeric rate limits for the MCP server, and its responses carry no x-ratelimit-* or Retry-After headers. Treat the limits as unpublished rather than absent: an agent left in a loop can issue a lot of calls very quickly, so build the usual defences instead of relying on the server to push back.

• Reuse the sessionOne initialize per client, not per tool call. Re-handshaking on every request triples your traffic for no benefit.
• Back off on transport errorsRetry 5xx responses and timeouts with exponential backoff. Do not retry a result.isError auth failure — bad credentials stay bad, and retrying just multiplies the load.
• Set a timeoutThe service can cold-start, so give the first request room. This portal allows ten seconds for its whole build-time handshake, which is a reasonable starting point.
• Keep concurrency modestPrefer sequential calls within a session. If you need throughput beyond a handful of concurrent requests, talk to us first so we can tell you what the backend will take.

Troubleshooting

The failures we see most often, and what each one actually means:

Every call after connecting returns 400 Missing session ID

Your client is not echoing the mcp-session-id header. Read it from the initialize response headers and attach it to every subsequent request.

Calls that worked earlier now return 404 Session not found

The server no longer recognises that session id — it may have expired, or the server may have restarted. Run initialize again and switch to the new id; session ids are not durable.

404 Not Found: Session has been terminated

Something already sent DELETE for that session. Start a fresh one with initialize.

406 Not Acceptable

The Accept header must offer application/json and text/event-stream together. Some HTTP clients default to */* or application/json only.

Access denied: Authentication error occurred, but the HTTP status is 200

That is the expected shape for an auth failure, not a bug — the server reports it on the result rather than the status line. Check that both x-api-key and organisation are present and correct; the server answers identically whether the headers are absent or simply wrong, so the message alone will not tell you which.

Claude Desktop connects but every tool call is denied

mcp-remote splits --header values on whitespace, so "x-api-key: KEY" loses everything after the space. Use the env-var form shown above, with no space after the colon.

The client shows no tools at all

tools/list needs no credentials, so an empty list points at the connection or the client config rather than your API key. Confirm the endpoint URL and that your network allows streaming responses.