MCP streamable HTTP endpoint

POST

/mcp

const url = 'https://api.satellitedata.net/mcp';
const options = {
  method: 'POST',
  headers: {
    'Mcp-Session-Id': 'mcp_5bJ8yQ2nVt',
    'MCP-Protocol-Version': '2025-06-18',
    'X-API-Key': '<X-API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"timeseries","arguments":{"lon":-93.25,"lat":44.95,"datetime":"2026-06-01T00:00:00Z/2026-08-31T23:59:59Z","index":"ndvi"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.satellitedata.net/mcp \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --header 'Mcp-Session-Id: mcp_5bJ8yQ2nVt' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "timeseries", "arguments": { "lon": -93.25, "lat": 44.95, "datetime": "2026-06-01T00:00:00Z/2026-08-31T23:59:59Z", "index": "ndvi" } } }'

Model Context Protocol server over streamable HTTP. AI agents call initialize, tools/list and tools/call with JSON-RPC 2.0; the tools are search, collections, render, statistics and timeseries, each a thin wrapper over the REST route of the same purpose. Tool calls cost the units of the route they call.

Authorizations

ApiKey
OAuth2
data
Session

Parameters

Header Parameters

Mcp-Session-Id

string

Session id returned by the initialize response; required on every later request.

Example

mcp_5bJ8yQ2nVt

MCP-Protocol-Version

string

Negotiated MCP protocol version.

Example

2025-06-18

Request Body^required

One JSON-RPC message.

application/json

MCP JSON-RPC 2.0 message.

object

jsonrpc

required

Always 2.0.

string

Allowed value: 2.0

Request id; absent on notifications.

string | integer

method

required

MCP method, such as initialize, tools/list or tools/call.

string

params

Method parameters.

object

key

additional properties

any

Example

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "timeseries",
    "arguments": {
      "lon": -93.25,
      "lat": 44.95,
      "datetime": "2026-06-01T00:00:00Z/2026-08-31T23:59:59Z",
      "index": "ndvi"
    }
  }
}

Responses

200

JSON-RPC response, or an SSE stream when the client accepts text/event-stream.

MCP JSON-RPC 2.0 response.

object

jsonrpc

required

Always 2.0.

string

Allowed value: 2.0

required

Id of the request answered.

string | integer

result

Result.

object

key

additional properties

any

error

Error.

object

code

required

JSON-RPC error code.

integer

message

required

Message.

string

data

Extra data.

object

key

additional properties

any

Example

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "4 observations; NDVI 0.518 on 2026-06-12 (sentinel-2c), masked on 2026-06-24 (landsat-9), 0.781 on 2026-07-12 (sentinel-2c), 0.769 on 2026-07-18 (landsat-8)."
      }
    ],
    "structuredContent": {
      "geometry": {
        "type": "Point",
        "coordinates": [
          -93.25,
          44.95
        ]
      },
      "collections": [
        "optical-sr"
      ],
      "index": "ndvi",
      "harmonize": "bandpass_adjusted",
      "count": 4,
      "series": [
        {
          "datetime": "2026-06-12T17:21:20Z",
          "itemId": "S2C_T15TVK_20260612T171605_L2A",
          "collection": "sentinel-2-l2a",
          "platform": "sentinel-2c",
          "value": 0.518,
          "validFraction": 1,
          "harmonization": "bandpass_adjusted"
        },
        {
          "datetime": "2026-06-24T16:58:28Z",
          "itemId": "LC09_L2SP_027029_20260624_02_T1",
          "collection": "landsat-ot-l2",
          "platform": "landsat-9",
          "value": null,
          "validFraction": 0,
          "harmonization": "offset_removed"
        },
        {
          "datetime": "2026-07-12T17:21:21Z",
          "itemId": "S2C_T15TVK_20260712T171233_L2A",
          "collection": "sentinel-2-l2a",
          "platform": "sentinel-2c",
          "value": 0.781,
          "validFraction": 1,
          "harmonization": "bandpass_adjusted"
        },
        {
          "datetime": "2026-07-18T16:58:29Z",
          "itemId": "LC08_L2SP_027029_20260718_02_T1",
          "collection": "landsat-ot-l2",
          "platform": "landsat-8",
          "value": 0.769,
          "validFraction": 1,
          "harmonization": "offset_removed"
        }
      ],
      "attribution": "Contains modified Copernicus Sentinel data 2026; Landsat data courtesy of the U.S. Geological Survey"
    },
    "isError": false
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

X-Units-Spent

number

Units charged for this response; 0 for cache hits and free routes.

Example

1.333

X-Units-Remaining

number

Units left this month before restricted mode.

Example

8664.2

RateLimit

string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example

"units";r=287;t=41

RateLimit-Policy

string

Quota policy of the caller (IETF RateLimit header draft).

Example

"units";q=300;w=60

Mcp-Session-Id

string

MCP session id, sent on the initialize response.

Example

mcp_5bJ8yQ2nVt

202

Accepted a notification or response; the body is empty.

text/plain

string

400

Not a JSON-RPC message, or a missing session header.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-mcp-message",
  "title": "Invalid MCP message",
  "status": 400,
  "detail": "Mcp-Session-Id is required after initialize.",
  "instance": "/mcp",
  "code": "invalid-mcp-message",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

The API key or bearer token is missing, unknown, revoked or expired.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-key",
  "title": "Invalid or missing credentials",
  "status": 401,
  "detail": "Send a verified key in X-API-Key or a bearer token from /oauth/token.",
  "instance": "/v1/process",
  "code": "invalid-key",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

WWW-Authenticate

string

Challenge naming the accepted schemes.

Example

Bearer realm="satellitedata.net", ApiKey header="X-API-Key"

404

The session expired; start again with initialize.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/mcp-session-expired",
  "title": "MCP session expired",
  "status": 404,
  "detail": "Session mcp_5bJ8yQ2nVt expired after 30 minutes idle.",
  "instance": "/mcp",
  "code": "mcp-session-expired",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

A per-minute, concurrency, monthly or per-IP limit was hit. Retry-After says when to retry.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key spent 300 of its 300 units in the current minute.",
  "instance": "/v1/process",
  "code": "rate-limited",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 17,
  "limits": {
    "unitsPerMinute": 300,
    "unitsSpentThisMinute": 300
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

RateLimit

string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example

"units";r=287;t=41

RateLimit-Policy

string

Quota policy of the caller (IETF RateLimit header draft).

Example

"units";q=300;w=60

500

An unexpected server error. No units are charged.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The request failed on our side and was logged. No units were charged.",
  "instance": "/v1/process",
  "code": "internal",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

MCP streamable HTTP endpoint

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Example

Responses

200

Example

Headers

Example

Example

Example

Example

Example

Example

202

400

Example

Headers

Example

401

Example

Headers

Example

Example

404

Example

Headers

Example

429

Example

Headers

Example

Example

Example

Example

500

Example

Headers

Example

Request Body^required