Adding tools

Application tools are registered once and shared by both the in-app AI Agent and the MCP Server. They always run through your existing oRPC procedures, so validation and permissions stay in one place.

Tools live in packages/api/lib/tools, with one file or folder per domain. Registering an API endpoint does not expose it automatically; you must add it to the shared applicationTools array.

Example

The included list_notifications tool is a complete reference implementation:

{
	name: "list_notifications",
	label: "List notifications",
	description: "List the current user's recent notifications and their read state.",
	scope: "mcp:read",
	input: listNotificationsInput,
	output: listNotificationsOutput,
	procedure: listNotifications,
	executionMode: "sequential",
	invalidates: [],
}

Registration steps

1. Write or reuse an oRPC procedure and export its Zod schemas.
2. Add a domain file under packages/api/lib/tools/.
3. Include the tool in applicationTools.
4. Declare the OAuth scope and execution policy.
5. For mutations, declare invalidation tags so connected clients refresh affected views.

Names must be JavaScript identifiers, such as list_records.

Permissions

MCP clients act as the signed-in user, but they are not browser sessions. The server verifies the OAuth token and then invokes the procedure with that user's identity.

• Use authenticatedProcedure for user-scoped procedures shared with MCP.
• Use protectedProcedure for operations that require a real login session.
• Always check current account status and permissions inside the procedure.

Tool failures remain failures. A later error does not undo an earlier mutation, and neither adapter automatically retries a failed program.