:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Hand-written tools
This guide covers hand-written tools only.
Most tools are generated from products/<product>/mcp/tools.yaml.
For those, follow the implementing MCP tools skill and the handbook guide.
To change a generated tool's request or error handling, use hooks: in its tools.yaml instead of a hand-written tool with the same name.
Write a tool by hand only when codegen cannot express it.
Examples are tools that call several endpoints or reshape the response.
Existing hand-written tools live in the folders next to this file, for example featureFlags/.
Quick start
- Create the handler.
Export a factory that returns a
ToolBase(seetypes.ts). Copy the structure of a nearby hand-written tool. - Register the factory in
TOOL_MAPinindex.ts. - Add the definition to
schema/tool-definitions.json. - Add unit tests under
services/mcp/tests/unit/.
The factory returns the name, input schema, and handler. Title, description, scopes, and annotations come from the JSON definition.
Tool definition
Each entry in schema/tool-definitions.json needs a clear description, a feature, the required scopes, and annotations:
{
"my-tool-name": {
"title": "My tool",
"description": "What the tool does and what the agent should do next.",
"category": "Feature flags",
"feature": "flags",
"summary": "One-line summary for the docs.",
"required_scopes": ["feature_flag:read"],
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true,
"readOnlyHint": true
}
}
}
featuremust be lowercase snake_case (for exampleerror_tracking).scripts/yaml-config-schema.tsdefines the rule.- Use the highest scope the tool needs: write if it changes data, read if it only reads.
categoryandsummaryappear in the docs. The MCP client does not read them.- Tool names are lowercase kebab-case.
If you add a new feature, also list it in the feature list in services/mcp/README.md and add it to tests/unit/tool-filtering.test.ts.
Schema Design Philosophy
Input Schemas
- Be strict: Validate inputs thoroughly to catch errors early
- Be user-friendly: Design inputs around what users naturally want to provide
- Be minimal: Only require essential fields, make others optional
- Be clear: Use descriptive names that don't require API knowledge
Output Schemas
- Be permissive: Don't fail on unexpected fields from the API
- Be comprehensive: Include useful information in responses, but don't stuff the context window with unnecessary information
- Add context: Include helpful URLs, descriptions, or related data
- Be consistent: Use similar patterns across tools