# Administration

## List Categories

`TOOL discourse_list_categories`

Exhaustively list categories visible to the selected identity through bounded pagination. Returns stable IDs, slugs, hierarchy (parent_category_id; pid is a legacy alias), access flags, counts, structured completion metadata, and JSON text fallback. Opt in with the administration toolset.

Authentication: no security requirement declared for this operation.

Parameters:

- `term` (argument, string, optional)
  Type: string
  
  minLength: 1
  
  maxLength: 250

- `max_pages` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 40

- `max_requests` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 40

- `max_results` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 1000

- `deadline_ms` (argument, integer, optional)
  Type: integer
  
  minimum: 100
  
  maximum: 120000

Returns:

Type: object

- `categories` (required)
  Type: Array<object>
  
  Items:
    Type: object
    
    - `id` (required)
      Type: integer
      
      exclusiveMinimum: 0
    
    - `name` (required)
      Type: string
      
      minLength: 1
    
    - `slug` (required)
      Type: string
      
      minLength: 1
    
    - `pid` (required)
      Type: integer | null
      
      anyOf:
        Type: integer
        
        exclusiveMinimum: 0
      
        Type: null
    
    - `parent_category_id` (required)
      Type: integer | null
      
      anyOf:
        Type: integer
        
        exclusiveMinimum: 0
      
        Type: null
    
    - `read_restricted` (required)
      Type: boolean
    
    - `topic_count` (required)
      Type: integer
      
      minimum: 0
    
    - `post_count` (required)
      Type: integer
      
      minimum: 0
    
    - `perms` (optional)
      Type: Array<object>
      
      Items:
        Type: object
        
        - `gid` (required)
          Type: integer
          
          minimum: 0
        
        - `perm` (required)
          Type: integer
        
        Additional properties: false
    
    Additional properties: true

- `meta` (required)
  Type: object
  
  - `total` (required)
    Type: integer
    
    minimum: 0
  
  - `reported_total` (required)
    Type: integer | null
    
    anyOf:
      Type: integer
      
      minimum: 0
    
      Type: null
  
  - `pages_fetched` (required)
    Type: integer
    
    minimum: 0
  
  - `complete` (required)
    Type: boolean
  
  - `has_more` (required)
    Type: boolean
  
  - `truncated_reason` (optional)
    Type: string
    
    enum: ["page_limit","deadline","cancelled","no_new_ids","total_mismatch","legacy_site_json","anonymous_fallback","upstream_error"]
  
  - `error` (optional)
    Type: string
  
  Additional properties: false

Additional properties: false

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_categories",
    "arguments": {
        "term": "string",
        "max_pages": 1,
        "max_requests": 1,
        "max_results": 1,
        "deadline_ms": 100
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_categories",
  "arguments": {
    "term": "string",
    "max_pages": 1,
    "max_requests": 1,
    "max_results": 1,
    "deadline_ms": 100
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_categories", arguments={
  "term": "string",
  "max_pages": 1,
  "max_requests": 1,
  "max_results": 1,
  "deadline_ms": 100
})
```


## List Site Settings

`TOOL discourse_list_site_settings`

List admin-visible Discourse site settings with bounded metadata, optionally returning only settings whose current value differs from the default. Secret and credential-like values are always masked.

Authentication: no security requirement declared for this operation.

Parameters:

- `categories` (argument, Array<string>, optional)
  Type: Array<string>
  
  maxItems: 50
  
  Items:
    Type: string
    
    minLength: 1
    
    maxLength: 200

- `plugin` (argument, string, optional)
  Type: string
  
  maxLength: 200

- `names` (argument, Array<string>, optional)
  Type: Array<string>
  
  maxItems: 100
  
  Items:
    Type: string
    
    maxLength: 200
    
    pattern: "^[a-z0-9_]+$"

- `overridden_only` (argument, boolean, optional)
  Type: boolean

- `offset` (argument, integer, optional)
  Type: integer
  
  minimum: 0

- `limit` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 500

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_site_settings",
    "arguments": {
        "categories": [
          "string"
        ],
        "plugin": "string",
        "names": [
          "string"
        ],
        "overridden_only": true,
        "offset": 0,
        "limit": 1
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_site_settings",
  "arguments": {
    "categories": [
      "string"
    ],
    "plugin": "string",
    "names": [
      "string"
    ],
    "overridden_only": true,
    "offset": 0,
    "limit": 1
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_site_settings", arguments={
  "categories": [
    "string"
  ],
  "plugin": "string",
  "names": [
    "string"
  ],
  "overridden_only": true,
  "offset": 0,
  "limit": 1
})
```


## Manage User Activation

`TOOL discourse_manage_user_activation`

Activate, approve, activate-and-approve, or deactivate one user through Discourse's authoritative admin routes. Requires explicit confirmation and upstream staff authorization.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required)
  Type: string
  
  minLength: 1

- `action` (argument, string, required)
  Type: string
  
  enum: ["activate","approve","activate_and_approve","deactivate"]

- `confirm` (argument, boolean, required) - Must be true because this changes account access state
  Type: boolean
  
  Must be true because this changes account access state
  
  const: true

Declared MCP annotations:

```json
{
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_manage_user_activation",
    "arguments": {
        "username": "string",
        "action": "activate",
        "confirm": true
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_manage_user_activation",
  "arguments": {
    "username": "string",
    "action": "activate",
    "confirm": true
  }
});
```

### Python

```python
result = await session.call_tool("discourse_manage_user_activation", arguments={
  "username": "string",
  "action": "activate",
  "confirm": true
})
```