MCP protocol¶

Version¶

kartoza-mcp implements Model Context Protocol version 2024-11-05 via github.com/mark3labs/mcp-go.

Transport¶

JSON-RPC 2.0 over standard I/O. The server reads framed messages on stdin and writes framed messages on stdout. stderr is reserved for human-readable logs.

Server metadata¶

{
  "name": "Spatial Clustering Server",
  "version": "1.0.0",
  "capabilities": {
    "tools": {}
  }
}

Lifecycle¶

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Server
    C->>S: initialize
    S-->>C: initialize result (capabilities)
    C->>S: notifications/initialized
    C->>S: tools/list
    S-->>C: tools result
    loop per analytic call
      C->>S: tools/call cluster_points
      S-->>C: tool result (GeoJSON)
    end
    C-)S: SIGTERM / EOF

Tool listing¶

tools/list returns:

{
  "tools": [
    {
      "name": "cluster_points",
      "description": "Clusters GeoJSON points and returns them as circles (polygons).",
      "inputSchema": { ... }
    }
  ]
}

Error semantics¶

Errors propagate as JSON-RPC error objects with codes:

Code	Meaning
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params (missing `geojson`, wrong type, …)
`-32603`	Internal error
`-32000`	Tool execution error (e.g. malformed GeoJSON)