{ "openapi": "3.1.0", "info": { "title": "Geoapify MCP Search Places Tool", "version": "0.1.0", "description": "OpenAPI specification for calling the Geoapify MCP search_places tool through the JSON-RPC endpoint." }, "servers": [ { "url": "https://api.geoapify.com/v1" } ], "tags": [ { "name": "MCP Search Places", "description": "Call the Geoapify MCP search_places tool through the JSON-RPC endpoint." } ], "paths": { "/mcp": { "post": { "tags": [ "MCP Search Places" ], "operationId": "callMcpSearchPlaces", "summary": "Call the search_places MCP tool", "description": "Call the search_places MCP tool with a JSON-RPC tools/call request.", "parameters": [ { "name": "apiKey", "in": "query", "required": true, "description": "Geoapify API key.", "schema": { "type": "string" }, "example": "YOUR_API_KEY" } ], "requestBody": { "description": "JSON-RPC request body for the search_places MCP tool.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPlacesToolCallRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "catering.restaurant", "lat": 52.52, "lon": 13.405, "radius_meters": 2000, "limit": 20, "lang": "en" } } }, "examples": { "searchPlaces": { "summary": "Search places", "description": "Find places and points of interest by category near geographic coordinates.", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "catering.restaurant", "lat": 52.52, "lon": 13.405, "radius_meters": 2000, "limit": 20, "lang": "en" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response for the MCP tool call.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolCallResponse" }, { "$ref": "#/components/schemas/JsonRpcErrorResponse" } ] } } } }, "400": { "description": "Invalid request payload or tool arguments." }, "401": { "description": "Missing or invalid Geoapify API key." }, "429": { "description": "Rate limit or quota exceeded." }, "500": { "description": "Internal gateway error." } } } } }, "components": { "schemas": { "SearchPlacesToolCallRequest": { "type": "object", "description": "JSON-RPC tools/call request for the search_places MCP tool.", "additionalProperties": false, "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "description": "JSON-RPC protocol version.", "const": "2.0" }, "id": { "description": "Client-supplied JSON-RPC request id echoed in the response.", "$ref": "#/components/schemas/JsonRpcId" }, "method": { "description": "MCP method used to call a tool.", "const": "tools/call" }, "params": { "description": "Tool call parameters for search_places.", "$ref": "#/components/schemas/SearchPlacesToolCallParams" } }, "examples": [ { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_places", "arguments": { "category": "catering.restaurant", "lat": 52.52, "lon": 13.405 } } } ], "x-geoapify-mcp-tool": "search_places", "x-geoapify-mcp-category": "Places", "x-geoapify-mcp-input-schema": "#/components/schemas/SearchPlacesInput", "x-geoapify-mcp-output-schema": "#/components/schemas/SearchPlacesOutput" }, "JsonRpcId": { "description": "JSON-RPC request identifier. The server echoes this value in the response.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "SearchPlacesToolCallParams": { "type": "object", "description": "MCP tools/call params for search_places.", "additionalProperties": false, "required": [ "name", "arguments" ], "properties": { "name": { "description": "Registered MCP tool name.", "const": "search_places" }, "arguments": { "description": "Arguments validated by the search_places input schema.", "$ref": "#/components/schemas/SearchPlacesInput" } } }, "SearchPlacesInput": { "type": "object", "additionalProperties": false, "required": [ "category", "lat", "lon" ], "properties": { "category": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9_-]+(?:\\.[a-z0-9_-]+)*$", "description": "Place category to find. Call list_place_categories first to get the supported category values." }, "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude of the search center." }, "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude of the search center." }, "radius_meters": { "type": "number", "minimum": 1, "description": "Optional search radius in meters. When omitted, returns the nearest matching places without a hard distance limit." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of places to return." }, "lang": { "type": "string", "default": "en", "description": "Result language as a supported two-letter language code." } } }, "SearchPlacesOutput": { "type": "object", "additionalProperties": false, "required": [ "category", "coordinates", "count", "results" ], "properties": { "category": { "type": "string", "description": "The supported place category used for this search." }, "coordinates": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "radius_meters": { "type": "number" }, "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Place result with common address and location properties. Additional fields may be returned depending on the place category and available source data.", "properties": { "name": { "type": "string" }, "formatted": { "type": "string", "description": "Formatted address or place label." }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Supported place categories assigned to the result." }, "housenumber": { "type": "string" }, "street": { "type": "string" }, "neighbourhood": { "type": "string" }, "suburb": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postcode": { "type": "string" }, "state": { "type": "string" }, "state_code": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" } } } } } }, "ToolCallResponse": { "type": "object", "description": "Successful JSON-RPC response for tools/call. Tool failures are returned with isError set to true.", "additionalProperties": false, "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "$ref": "#/components/schemas/JsonRpcId" }, "result": { "type": "object", "additionalProperties": false, "required": [ "content", "isError" ], "properties": { "content": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string" } } } }, "structuredContent": { "description": "Structured output returned by the search_places tool.", "$ref": "#/components/schemas/SearchPlacesOutput" }, "isError": { "type": "boolean" } } } } }, "JsonRpcErrorResponse": { "type": "object", "description": "JSON-RPC error response returned for invalid requests or unknown methods.", "additionalProperties": false, "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "$ref": "#/components/schemas/JsonRpcId" }, "error": { "$ref": "#/components/schemas/JsonRpcError" } } }, "JsonRpcError": { "type": "object", "description": "JSON-RPC error object.", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": true } } } } }