API Reference

Overview

Each Hopkin MCP server publishes an OpenAPI 3.1 specification that documents every available tool as a REST-style endpoint. These specs are auto-generated from the same Zod schemas that power the MCP tools, so they're always in sync with the live servers.

What's Inside

Each spec maps MCP tools to POST /tools/{tool_name} endpoints with:

  • Full input schemas — every parameter, type, and constraint
  • Request examples — real parameter combinations you can try
  • Response schemas — success and error shapes
  • MCP extensions — x-mcp-annotations (read-only, destructive, idempotent), x-mcp-tool-type, and x-mcp-chart-types

How to Use

Swagger UI / Redoc

Import the JSON URL directly into Swagger Editor or any OpenAPI viewer to browse tools interactively.

Postman / Insomnia

Import the spec file to auto-generate a collection of all tool endpoints with pre-filled request bodies.

Code Generation

Use openapi-generator or similar tools to generate typed API clients in any language.

LLM Context

The specs serve as structured context for AI tools that need to understand available capabilities.

Authentication

All endpoints require a Bearer token — either a Supabase JWT from the OAuth flow or an API key (hpk_live_...). See the Authentication docs for details.

Available Specs