list_oncall_users

Retrieve on-call users from Grafana OnCall, including all users, specific users by ID, or filtered by username with pagination support.

Instructions

List users from Grafana OnCall. Can retrieve all users, a specific user, or filter by username

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	The page number to return
`userId`	No	The ID of a specific user to retrieve
`username`	No	Username to filter by

Implementation Reference

src/tools/oncall.ts:121-153 (handler)

Handler function that creates an API client, queries the Grafana OnCall users endpoint based on input parameters, formats the user data, and returns the result or error.

handler: async (params, context: ToolContext) => {
  try {
    const client = createOncallClient(context.config.grafanaConfig);
    
    const queryParams: any = {};
    if (params.username) queryParams.username = params.username;
    if (params.page) queryParams.page = params.page;
    
    let endpoint = '/users';
    if (params.userId) {
      endpoint = `/users/${params.userId}`;
    }
    
    const response = await client.get(endpoint, { params: queryParams });
    
    const users = params.userId ? [response.data] : response.data.results || [];
    
    // Format the response
    const formatted = users.map((user: any) => ({
      id: user.id,
      username: user.username,
      email: user.email,
      name: user.name,
      role: user.role,
      timezone: user.timezone,
      teams: user.teams,
    }));
    
    return createToolResult(formatted);
  } catch (error: any) {
    return createErrorResult(error.response?.data?.detail || error.message);
  }
},

src/tools/oncall.ts:16-20 (schema)

Zod input schema for the list_oncall_users tool, defining optional parameters for userId, username, and page.

const ListOncallUsersSchema = z.object({
  userId: z.string().optional().describe('The ID of a specific user to retrieve'),
  username: z.string().optional().describe('Username to filter by'),
  page: z.number().optional().describe('The page number to return'),
});

src/tools/oncall.ts:223-223 (registration)
Direct registration of the listOncallUsers tool definition with the MCP server inside registerOncallTools function.
```
server.registerTool(listOncallUsers);
```

src/tools/oncall.ts:31-47 (helper)

Helper function to create an Axios HTTP client configured for the Grafana OnCall API using the provided grafanaConfig.

function createOncallClient(config: any) {
  const headers: any = {
    'User-Agent': 'mcp-grafana/1.0.0',
  };
  
  if (config.serviceAccountToken) {
    headers['Authorization'] = `Bearer ${config.serviceAccountToken}`;
  } else if (config.apiKey) {
    headers['Authorization'] = `Bearer ${config.apiKey}`;
  }
  
  return axios.create({
    baseURL: `${config.url}/api/plugins/grafana-oncall-app/resources/api/v1`,
    headers,
    timeout: 30000,
  });
}

src/cli.ts:119-120 (registration)
Conditional invocation of registerOncallTools to register OnCall tools, including list_oncall_users, when 'oncall' category is enabled.
```
if (enabledTools.has('oncall')) {
  registerOncallTools(server);
```

Grafana MCP Server