implementing-mcp-tools

Implementing MCP tools

Read the full guide at docs/published/handbook/engineering/ai/implementing-mcp-tools.md.

Quick workflow

# 1. Scaffold a starter YAML with all operations disabled.
#    --product discovers endpoints via their x-product attribution.
#    ViewSets in products/<name>/backend/ are auto-attributed via module
#    path. ViewSets elsewhere need
#    @extend_schema(extensions={"x-product": "<product>"}).
pnpm --filter=@posthog/mcp run scaffold-yaml -- --product your_product \
    --output ../../products/your_product/mcp/tools.yaml

# 2. Configure the YAML — enable tools, add scopes, annotations, descriptions
#    Place in products/<product>/mcp/*.yaml (preferred) or services/mcp/definitions/*.yaml

# 3. Add a HogQL system table in posthog/hogql/database/schema/system.py
#    and a model reference in products/posthog_ai/skills/querying-posthog-data/references/

# 4. Generate handlers and schemas
hogli build:openapi

Before you scaffold: fix the backend first

The codegen pipeline can only generate correct tools if the Django backend exposes correct types. Read the type system guide for the full picture.

Before scaffolding YAML, verify:

1. Serializers have explicit field types and help_text — these flow all the way to Zod .describe() in the generated tool. Missing descriptions = agents guessing at parameters. Use ListField(child=serializers.CharField()) instead of bare ListField(), and @extend_schema_field(PydanticModel) on JSONField subclasses to get typed Zod output (see products/alerts/backend/api/alert.py for the pattern).
2. Plain ViewSet methods have @extend_schema(request=...) — without it, drf-spectacular can't discover the request body and the generated tool gets z.object({}) (zero parameters). ModelViewSet with a serializer_class is fine; plain ViewSet with manual validation is not.
3. Query parameters use @validated_request or @extend_schema with a query serializer — otherwise boolean and array query params may produce type mismatches in the generated code.