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
    route_filters.py    # openapi.tools_filter → FastMCP route_map_fn
    server.py           # reloadable HTTP MCP server

Related MCP server: OpenAPI MCP Server

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 (this is how the Caflou instance authorizes upstream requests):

api:
  base_url: https://app.caflou.com
  headers:
    Authorization: "Bearer ${CAFLOU_API_TOKEN}"

Example sanitizer settings for problematic OpenAPI response schemas:

openapi:
  sanitizer:
    enabled: true
    on_unresolved: replace_generic
    paginated_lists:
      enabled: true
      items_key: results

The sanitizer only touches response schemas. It inlines local #/components/schemas/... refs before handing the spec to FastMCP. If recursive or otherwise unresolved local refs remain, replace_generic swaps the affected response schema for a generic object so MCP clients can still load the tool.

When paginated_lists.enabled is true, GET operations that accept page or per query parameters and declare a bare JSON array response are rewritten to a minimal object envelope (page, results, additionalProperties: true). Extra pagination fields from the live API (prev_page, total_results, etc.) are allowed via additionalProperties and do not need to be listed explicitly. The envelope uses OpenAPI 3.0 syntax only (no JSON Schema union types such as type: ["integer", "null"], which FastMCP's spec parser rejects).

OpenAPI patch files

If the upstream spec is incomplete or needs local corrections, you can layer one or more patch files on top of the downloaded spec before FastMCP ingests it:

openapi:
  spec: https://app.caflou.com/api/v1/i/docs/openapi/v1/openapi.yaml
  patch_files:
    - examples/caflou.accounts.patch.yaml

Patch files are parsed as YAML/JSON objects and deep-merged into the OpenAPI document. Mappings are merged recursively; lists are replaced in full. This keeps the server spec-driven even when the upstream file is re-downloaded periodically. Relative patch paths are resolved against the directory of the primary config file (the first file in MCP_HOOKER_CONFIG_FILES, or config.yaml by default).

In Docker, mount patch files into that same directory inside the container. If config.yaml is mounted at /app/config.yaml, then patch.yaml must also be available at /app/patch.yaml:

volumes:
  - ./config.yaml:/app/config.yaml:ro
  - ./patch.yaml:/app/patch.yaml:ro

Example Caflou patch for the missing GET /api/v1/accounts endpoint:

paths:
  /api/v1/accounts:
    get:
      tags:
        - Accounts
      operationId: List_Accounts
      summary: List accounts
      responses:
        "200":
          description: Accounts visible to the current token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                required:
                  - result
                x-fastmcp-wrap-result: true

The repository includes that example as examples/caflou.accounts.patch.yaml. After reload, FastMCP should expose a generated List_Accounts MCP tool if the upstream API accepts the request.

Set the value via the environment (never commit it). With Docker Compose, copy .env.example to .env and fill in CAFLOU_API_TOKEN; the token is passed into the container and injected on every upstream call. See docs/RUNBOOK.md §4 (auth) and §6 (production deployment).

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.

Voicebot ↔ Caflou (ElevenLabs): docs/voicebot-caflou-mcp.md — patch limits, filtered caflou-voice instance, thin MCP via voicebot-core. Sync Caflou project 615009: scripts/caflou_sync_voicebot_project.py.

License

MIT