MCP (Model Context Protocol) server for HawkAPI. Auto-exports every route as an agent tool — any MCP-compatible client can call your API.
pip install hawkapi-mcpfrom 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 /mcpPoint 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.
| 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 |
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.
mount_mcp(app, include_only={"get_user", "create_item"})
mount_mcp(app, exclude={"internal_admin_route"})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.
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.
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/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).
MIT.