hawkapi-mcp

MCP (Model Context Protocol) server for HawkAPI. Auto-exports every route as an agent tool — any MCP-compatible client can call your API.

Install

pip install hawkapi-mcp

Quickstart

from hawkapi import HawkAPI
from hawkapi.responses import JSONResponse
from hawkapi_mcp import mount_mcp

app = HawkAPI()

@app.get("/users/{user_id:int}")
async def get_user(user_id: int) -> JSONResponse:
    return JSONResponse({"id": user_id, "name": "Alice"})

@app.post("/items")
async def create_item(body: dict) -> JSONResponse:
    return JSONResponse({"created": body})

mount_mcp(app)  # serves POST /mcp

Point any MCP-compatible client at http://your-host/mcp. Every HawkAPI route becomes a tool — its operationId is the tool name, the OpenAPI schema becomes the input schema.

Tool naming

Route definition	Generated tool name
@app.get("/users/{id}", operation_id="get_user")	get_user
@app.get("/users/{id}") (no operation_id)	get_users_id

Tool input schema

The decorator combines path / query / header parameters and the JSON request body into a single object schema. Parameter names are namespaced so they cannot collide:

Source	Schema key
Path parameter	path.<name>
Query parameter	query.<name>
Header parameter	header.<name>
Cookie parameter	cookie.<name>
JSON body	body

tools/call example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_user",
    "arguments": {"path.user_id": "42"}
  }
}

The tool result has the response body in content[0].text and the raw HTTP status / headers in structuredContent. isError is true for any 4xx/5xx response.

Filtering tools

mount_mcp(app, include_only={"get_user", "create_item"})
mount_mcp(app, exclude={"internal_admin_route"})

Supported JSON-RPC methods

• initialize — handshake. Returns the MCP protocol version, server info, and tool capability.
• ping — keepalive.
• tools/list — return the tool catalog.
• tools/call — invoke a tool. Returns response body + HTTP status.
• notifications/initialized — accepted, no response.

The endpoint accepts both single JSON-RPC objects and batches.

Auth

hawkapi-mcp does not define its own auth layer — wire your HawkAPI middleware (HTTPBearer, OAuth2, API key) on the MCP route just like any other path. Header arguments forwarded by the client land in the request before middleware runs.

Development

git clone https://github.com/Hawk-API/hawkapi-mcp.git
cd hawkapi-mcp
uv sync --extra dev
uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run pyright src/

Specification

Implements a subset of the Model Context Protocol sufficient to advertise and invoke tools. Streamable HTTP transport only — stdio is out of scope (deploy your app behind any ASGI server and the agent connects to the /mcp URL).

License

MIT.