Connect with curl

Raw HTTP examples for every interaction your custom MCP client needs to support. Useful when you're building an integration in a language without an MCP SDK, or just probing the server.

What you need

• A ShipMCP endpoint URL: https://mcp.shipmcp.io/<your-slug>/mcp
• A bearer token from /endpoints (read-only) or an OAuth-issued token (read or read+write). See OAuth 2.0 for the OAuth dance.

1. Initialize

Always the first call. Returns server capabilities, name, and the all-important instructions field pointing at your llms.txt.

curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": { "protocolVersion": "2024-11-05" }
  }'

2. List tools

curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Inspect the returned tools[] array. Each entry has name, description, and inputSchema.

3. Call a tool

curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_documents",
      "arguments": { "limit": 5 }
    }
  }'

The result's content[] is an array of MCP content blocks. For our tools you'll see one {"type":"text","text":"..."} entry containing the JSON-encoded query result.

4. List + read resources

# resources/list
curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 4, "method": "resources/list" }'

# resources/read — pass a URI from the list above
curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "resources/read",
    "params": { "uri": "shipmcp://<your-slug>/1" }
  }'

Files ≤ 4 MB inline as base64 (blob field). Larger files come back as a text block with a 120-second signed URL the client can follow with a plain GET.

5. Async write (Pro+, mcp:write scope)

# Step 1: enqueue
curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "insert_documents",
      "arguments": {
        "title": "test",
        "content": "...",
        "url": "test://1",
        "kind": "text"
      }
    }
  }'
# → {"status":"queued","job_id":"abc-123",...}

# Step 2: poll
curl -s -X POST https://mcp.shipmcp.io/<your-slug>/mcp \
  -H "Authorization: Bearer smcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_write_job_by_id",
      "arguments": { "job_id": "abc-123" }
    }
  }'

Discovery without auth

Two well-known paths return useful info without any token:

# Resource metadata (RFC 9728)
curl https://mcp.shipmcp.io/.well-known/oauth-protected-resource

# Authorization Server metadata (RFC 8414)
curl https://shipmcp.io/.well-known/oauth-authorization-server

# Per-endpoint llms.txt
curl https://mcp.shipmcp.io/<your-slug>/llms.txt

Error envelope

Errors look like JSON-RPC. Common codes documented in MCP protocol. The HTTP layer can also return 401 (with WWW-Authenticate), 403 (token has wrong scope or wrong tenant), 429 (rate limit), or 503 (provisioning).