list_users
List all Capsule users with id, username, role, and party reference. Use returned user ids to filter opportunities, projects, and tasks by owner.
Instructions
List all users in the Capsule account. Returns each user's id, username, optional first/last name, role, and party reference. Some users may have null first/last name fields (only username set) — fall back to username for display. Use this to discover user ids for owner-filtered queries against opportunities, projects, and tasks, or to map a user to their party record via user.party.id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| perPage | No |
Implementation Reference
- src/tools/users.ts:14-20 (handler)The actual handler function for the list_users tool. Calls capsuleGet to fetch /users from the Capsule CRM API with pagination (page, perPage). Returns data along with nextPage from the Link header.
export async function listUsers(input: z.infer<typeof listUsersSchema>) { const { data, nextPage } = await capsuleGet<{ users: unknown[] }>("/users", { page: input.page ?? 1, perPage: input.perPage ?? 100, }); return { ...data, nextPage }; } - src/tools/users.ts:9-12 (schema)Zod schema for list_users input. Defines optional page (positive integer) and perPage (1-100 integer) parameters.
export const listUsersSchema = z.object({ page: z.number().int().positive().optional(), perPage: z.number().int().min(1).max(100).optional(), }); - src/server.ts:999-1005 (registration)Registration of the list_users tool on the MCP server. Calls registerTool with name 'list_users', description, listUsersSchema, and listUsers handler.
registerTool( server, "list_users", "List all users in the Capsule account. Returns each user's id, username, optional first/last name, role, and party reference. Some users may have null first/last name fields (only username set) — fall back to username for display. Use this to discover user ids for owner-filtered queries against opportunities, projects, and tasks, or to map a user to their party record via user.party.id.", listUsersSchema, listUsers, ); - src/server/register-tool.ts:39-59 (helper)The generic registerTool helper that wraps a handler's return value in the standard MCP text-content response format and registers it on the McpServer.
export function registerTool<Schema extends z.ZodObject<ZodRawShape>>( server: McpServer, name: string, description: string, schema: Schema, handler: (input: z.infer<Schema>) => Promise<unknown>, ): void { // Use the SDK config-form registerTool with the full Zod schema. The // deprecated shape overload rebuilds z.object(schema.shape), which drops // object-level refinements such as superRefine. const registerWithSchema = server.registerTool.bind(server) as ( toolName: string, config: { description: string; inputSchema: Schema }, callback: (input: z.infer<Schema>) => Promise<CallToolResult>, ) => void; registerWithSchema(name, { description, inputSchema: schema }, async (input) => { const result = await handler(input); return wrapAsText(result); }); }