Model Context Protocol (MCP)¶

DRAFT Specification / Work in Progress

This portion of the BTAA GIN site, our GeoBTAA API, and our Linked Data offerings are a WORK IN PROGRESS. Please reach out if you have questions or wish to participate in bringing these resources to public release.

The GeoBTAA API supports Model Context Protocol (MCP), a formal specification for declaring the processing and behavioral context of an API response. MCP enables generic clients, validators, and AI agents to understand how to interpret metadata records and response payloads in a consistent, machine-readable way.

Usage¶

GET /api/v1/mcp

{
  "name": "geobtaa-api",
  "version": "0.1.0",
  "description": "GeoBTAA API MCP Service",
  "protocol": "mcp",
  "transports": [
    "stdio",
    "websocket"
  ],
  "capabilities": {
    "tools": [
      "search_resources",
      "get_resource",
      "get_resource_ogm",
      "list_resources",
      "get_suggestions",
      "get_resource_viewer"
    ]
  },
  "connections": {
    "stdio": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "app.services.mcp_service"
      ]
    },
    "websocket": {
      "type": "websocket",
      "url": "/api/v1/mcp/ws"
    }
  },
  "documentation": {
    "tools": {
      "search_resources": "Search for geospatial resources using text queries, filters, and sorting options",
      "get_resource": "Get a single geospatial resource by ID with full metadata and UI enhancements",
      "get_resource_ogm": "Get just the OpenGeoMetadata Aardvark record for a resource by ID",
      "list_resources": "List all geospatial resources with pagination",
      "get_suggestions": "Get search suggestions for autocomplete",
      "get_resource_viewer": "Get an HTML page with the embedded OGM viewer for a specific resource"
    }
  }
}

Profile URIs¶

Each URI in the profile array MUST resolve to a valid MCP document, which includes:

@context: MUST include the MCP context (https://modelcontextprotocol.io/context/v1.jsonld)
@type: SHOULD be ModelContextProfile
title, description, appliesTo: for human/machine interpretation
features: optional keys describing supported behaviors, fields, or UI expectations

Example MCP Profile (abridged)¶

{
  "@context": "https://modelcontextprotocol.io/context/v1.jsonld",
  "@type": "ModelContextProfile",
  "id": "https://opengeometadata.org/profile/mcp/search",
  "title": "OGM Search Results Profile",
  "description": "Describes the structure and interpretation of search results.",
  "appliesTo": "https://opengeometadata.org/api/v1/search",
  "features": {
    "search": {
      "supportsGeoFilters": true,
      "maxResults": 1000,
      "defaultSort": "relevance"
    },
    "ui": {
      "viewer": true,
      "facets": true,
      "pagination": true
    }
  }
}

Benefits¶

Allows automated agents to reason about what’s returned
Enables consistent UI rendering and schema interpretation
Provides potential future extensibility without API versioning

TODOs¶

BTAA Examples instead of OGM Examples