Skip to content

🛠️ Tools Overview

Django Admin MCP generates tools dynamically based on your exposed models. This page provides an overview of all available tools.

📂 Tool Categories

Tools are organized into four categories:

Category Tools Description
📝 CRUD list_*, get_*, create_*, update_*, delete_* Basic data operations
⚡ Actions actions_*, action_*, bulk_* Admin actions and bulk operations
🔍 Introspection describe_*, find_models Model discovery and schema
🔗 Relationships related_*, history_*, autocomplete_* Related data and history

📛 Tool Naming Convention

Tools follow a consistent naming pattern:

<operation>_<model_name>

For example, for an Article model:

  • list_article — List articles
  • get_article — Get a single article
  • create_article — Create an article
  • update_article — Update an article
  • delete_article — Delete an article

🌐 Global Tools

One tool is available regardless of model configuration:

🔍 find_models

Discovers all registered models and their available tools. Results are filtered by the token's view permission.

{
  "method": "tools/call",
  "name": "find_models",
  "arguments": {}
}

Optional parameter:

  • query (string) — Filter models by name

Response:

{
  "count": 2,
  "models": [
    {
      "model_name": "article",
      "verbose_name": "Article",
      "verbose_name_plural": "Articles",
      "app_label": "blog",
      "tools_exposed": true
    },
    {
      "model_name": "author",
      "verbose_name": "Author",
      "verbose_name_plural": "Authors",
      "app_label": "blog",
      "tools_exposed": false
    }
  ]
}

📦 Per-Model Tools

For each model with mcp_expose = True, 12 tools are generated:

📝 CRUD Operations (5 tools)

Tool Permission Description
list_<model> view List instances with pagination, filtering, search
get_<model> view Get single instance by ID
create_<model> add Create new instance
update_<model> change Update existing instance
delete_<model> delete Delete instance

See CRUD Operations for details.

⚡ Admin Actions (3 tools)

Tool Permission Description
actions_<model> view List available admin actions
action_<model> change Execute an admin action
bulk_<model> varies Bulk create/update/delete

See Admin Actions for details.

🔍 Introspection (1 tool)

Tool Permission Description
describe_<model> view Get field definitions and metadata

See Model Introspection for details.

🔗 Relationships (3 tools)

Tool Permission Description
related_<model> view Get related objects
history_<model> view View change history
autocomplete_<model> view Search suggestions

See Relationships for details.

📐 Tool Schema

Each tool has a JSON Schema defining its input parameters:

{
  "name": "list_article",
  "description": "List all Article instances with pagination and filtering",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "integer",
        "description": "Maximum number of results",
        "default": 100
      },
      "offset": {
        "type": "integer",
        "description": "Number of results to skip",
        "default": 0
      },
      "search": {
        "type": "string",
        "description": "Search query"
      },
      "order_by": {
        "type": "array",
        "description": "Fields to order by (prefix with - for descending)"
      },
      "filters": {
        "type": "object",
        "description": "Field filters"
      }
    }
  }
}

📤 Response Format

All tools return responses in MCP TextContent format:

{
  "content": [
    {
      "type": "text",
      "text": "{ ... JSON data ... }"
    }
  ]
}

Error responses include isError: true:

{
  "content": [
    {
      "type": "text",
      "text": "Permission denied: blog.add_article"
    }
  ],
  "isError": true
}

🔒 Permission Requirements

Each tool requires specific Django permissions:

Operation Permission Pattern
Read operations <app>.view_<model>
Create <app>.add_<model>
Update <app>.change_<model>
Delete <app>.delete_<model>
Actions <app>.change_<model>

🔗 Next Steps