mcp-hooker

Configurable FastMCP server that turns any OpenAPI spec (local or remote, JSON or YAML) into an MCP tool surface over HTTP.

Configuration is YAML via yayaya — layered files, dot-path lookups, and ${ENV_VAR} expansion for secrets.

Project layout

mcp-hooker/
  pyproject.toml
  config.yaml           # default config (safe to commit)
  config.local.yaml     # optional overlay (gitignored)
  Dockerfile
  docker-compose.yml
  .gitlab-ci.yml
  docs/RUNBOOK.md
  mcp_hooker/
    settings.py         # yayaya loader
    spec_loader.py      # fetch/parse OpenAPI
    server.py           # reloadable HTTP MCP server

Related MCP server: ControlAPI-MCP

Quick start

cd mcp-hooker
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Edit config.yaml (openapi.spec + api.base_url), then:
mcp-hooker

The server listens on server.host / server.port from config (default 0.0.0.0:8000).

Configuration

Loaded from config.yaml, with optional config.local.yaml merged on top. Override paths with:

export MCP_HOOKER_CONFIG_FILES=config.yaml,config.docker.yaml

Keys

Example api.headers with a secret from the environment:

api:
  headers:
    Authorization: "Bearer ${API_TOKEN}"

HTTP endpoints

Reloading

• HTTP: curl -X POST http://localhost:8000/admin/reload

• Signal: kill -HUP <pid> when reload.on_sighup is true

• Interval: set reload.interval_seconds to poll remote specs

Each reload closes the previous httpx client, re-parses config via yayaya, fetches the spec, and rebuilds the FastMCP OpenAPI provider.

Docker

docker build -t mcp-hooker .
docker run --rm -p 8000:8000 -v "$PWD/config.yaml:/app/config.yaml:ro" mcp-hooker

Or with Compose:

docker compose up --build

GitLab CI/CD

.gitlab-ci.yml mirrors zpl-mcp: build on a tagged runner, push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA, and tag latest on the default branch.

Register a runner with tag mcp-hooker (or change the tag in .gitlab-ci.yml to match your fleet).

Cursor / MCP client

Point your client at the streamable HTTP URL, for example:

{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Development

pip install -e ".[dev]"
ruff check mcp_hooker

Operations

See docs/RUNBOOK.md for architecture, deployment notes, and troubleshooting.

License

MIT