Install and configure
Use Python 3.12 or Node.js 24.17 or newer. Install in a new project, using a virtual environment for Python:- Python
- TypeScript
Define the local tool and run the agent
TheHN_RESEARCH toolkit contains one local tool. The direct-tools preset puts that tool and HACKERNEWS_GET_USER directly in the agent’s tool list.
- Python
- TypeScript
Save as
research.py:research.py
HACKERNEWS_GET_USER and LOCAL_HN_RESEARCH_GET_USER_NOTE. It should not include COMPOSIO_SEARCH_TOOLS: the direct-tools preset exposes the allowed tools without a discovery step.
The answer should combine live profile information with the internal note about Paul Graham. Change pg to another username to see the local tool return No internal note found.
Preload selected tools while keeping discovery
Use the direct-tools preset when the agent’s allowed tool set is small and known ahead of time. For a larger catalog, keep the default session behavior and preload only the tools you expect to need immediately. The repository’s TypeScript preload example and Python preload example demonstrate that alternative:preload.toolsselects remote tools to expose immediately.preload: trueon a custom tool or toolkit exposes its local tools immediately.- Other allowed tools remain discoverable through search.
Replace the demo note with your application data
The local callback runs in your application process. It can query your database or call an internal service. Use the callback’sctx.userId in TypeScript or ctx.user_id in Python to enforce your application’s access rules before returning records. An ID supplied by the model is not proof of authorization.
Keep the SDK tool execution in your process for this pattern. The hosted MCP endpoint can’t invoke these in-process callbacks. Tool results still become model context, so return only the fields the model needs.
Custom tools and toolkits are experimental. See custom tools for extension tools, authenticated API calls, and callback context.