Model Context Protocol

Introduction

As of version 3.1.0, Geoportal Server supports the Model Context Protocol (MCP) to interact with the STAC API from agentic systems.

The Geoportal Server STAC MAP endpoint is accessible at /geoportal/mcp and follows MCP HTTP rules:

• Single endpoint: /geoportal/mcp
• Uses JSON-RPC 2.0: { "jsonrpc": "2.0", "method": "...", "params": {...} }
• Requires headers: Accept: application/json, text/event-stream

Mental model

           +-------------------------+
           |   AI Client (Copilot)   |
           +--  --------+--  --------+
                        |
                 MCP (JSON-RPC)
                        |
             https://.../geoportal/mcp
                        |
           +------------v------------+
           |     MCP Server Layer    |
           |    (tool definitions)   |
           +----------+----------+
                      |
              Geoportal STAC API
                      |
           +----------v--------------+
           | Geoportal Catalog       |
           | /collections            |
           | /collections/.../items  |
           | /search                 |
           +-------------------------+

Examples

Below are some examples in Python of interacting with the MCP API:

• Initialize request
• Get collections
• Search for items

These examples use the sandbox Geoportal Server at http://gpt.geocloud.com/geoportal. This is a small STAC catalog.

Initialize request

The initialize request is typically the first handshake call between the client (an AI app/agent) and the MCP server. Specifically, it lets the client:

• Verify the server is alive
• Negotiate protocol version
• Learn available:
  • tools
  • resources
  • prompts (not implemented at the moment)

import requests
import json

url = "https://gpt.geocloud.com/geoportal/mcp"

payload = json.dumps({
  "summary": "Initialize",
  "value": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "example-client",
        "version": "0.1.0"
      },
      "capabilities": {}
    }
  }
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

List available tools

An MCP tools request typically serves one or more of these purposes:

• Discover available tools
  • The client asks the server: “What functions or capabilities do you expose?”
  • The server responds with a list of tools (e.g., search, query catalog, fetch metadata).
• Understand tool schemas
  • Each tool includes: Name, Description, Input schema (parameters), Output structure
  • This allows the client (often an LLM) to know how to call the tool correctly.
• Enable dynamic integration
  • Rather than hardcoding APIs, the client can query tools at runtime and decide which tool to use based on user intent.
• Support function-calling workflows
  • After discovering tools, the client can generate a tool invocation request, pass structured arguments, or receive results and continue the interaction.

import requests
import json

url = "https://gpt.geocloud.com/geoportal/mcp"

payload = json.dumps({
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/list",
  "params": {}
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Get a collection

One of the tools provided is to get a STAC collection. The client passes the collectionId

import requests
import json

url = "https://gpt.geocloud.com/geoportal/mcp"

payload = json.dumps({
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "stac_get_collection",
    "arguments": {
      "collectionId": "sentinel-2-l2a"
    }
  }
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Search for items

import requests
import json

url = "https://gpt.geocloud.com/geoportal/mcp"

payload = json.dumps({
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "stac_search",
    "arguments": {
      "xbbox": "-0,-90,180,90",
      "xdatetime": "2025-01-01T00:00:00Z/2025-12-31T23:59:59Z",
      "xlimit": 2,
      "collections": [
        "sentinel-2-l2a"
      ]
    }
  }
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)