Two Different Problems, Two Different Tools

When Joomla developers first hear about the Model Context Protocol, a common reaction is: "Why do I need this? Joomla already has a REST API." It is a fair question. The Joomla MCP server sits on top of the REST API — it does not replace it. Understanding the distinction between MCP and direct API access reveals when each approach makes sense and why combining both is the right architecture for AI-integrated Joomla sites.

What the Traditional REST API Does

Joomla's REST API (introduced in Joomla 4.0) exposes site data and functionality through standard HTTP endpoints. A developer calls an endpoint, gets a JSON response, and does something with it. This is the right tool when:

• You are building a frontend application that reads Joomla content.
• You are writing a script that runs on a schedule to perform a specific operation.
• You need fine-grained control over request parameters, headers, and response handling.
• You are integrating Joomla with another system via a webhook or ETL pipeline.

The REST API is deterministic: you tell it exactly what to do, it does it. There is no interpretation, no planning, no decision-making. The intelligence lives entirely in the code you write.

What MCP Adds on Top

The Model Context Protocol is not an API — it is a protocol for connecting AI models to tools. An MCP server wraps your REST API calls in a structured declaration that an AI model can understand, plan with, and call autonomously.

The critical difference: with a REST API, a human developer decides which endpoints to call in which order. With MCP, the AI model makes those decisions — based on what the user asked for, what tools are available, and what previous tool calls returned.

Traditional API approach:
Developer → writes script → calls /api/v1/content/articles → processes response

MCP approach:
User → asks AI in natural language → AI calls list_articles tool 
→ AI calls get_article for relevant items → AI synthesises response

The same underlying API calls happen either way. MCP just changes who is deciding which calls to make.

Tool Schemas: The Key Ingredient

The mechanism that makes MCP work is the tool schema — a JSON description of what a tool does and what parameters it accepts. Here is an example for a Joomla article creation tool:

{
  "name": "create_article",
  "description": "Create a new article in Joomla. Returns the created article's ID and alias.",
  "inputSchema": {
    "type": "object",
    "required": ["title", "category_id"],
    "properties": {
      "title": {
        "type": "string",
        "description": "The article title"
      },
      "category_id": {
        "type": "number",
        "description": "ID of the target category"
      },
      "body": {
        "type": "string",
        "description": "HTML content of the article body"
      },
      "state": {
        "type": "number",
        "description": "Publication state: 1=published, 0=unpublished (default 0)"
      },
      "metadesc": {
        "type": "string",
        "description": "SEO meta description, 120-160 characters"
      }
    }
  }
}

This schema tells the AI model: what the tool is called, what each parameter means, which parameters are required, and what types are expected. The AI uses this schema to generate valid tool calls without any additional documentation or guidance. It also uses the descriptions to decide when to call the tool and why specific parameter values make sense.

Compare this to a raw REST API endpoint: the AI would need to know the exact URL, the correct HTTP method, the authentication header format, the request body structure, and how to interpret the response — and it would need to discover all of this from documentation or trial and error. MCP schemas package all of that knowledge into a structured declaration the AI can use directly.

Error Handling and Recovery

A traditional API call either succeeds or fails. Your script handles the failure however you coded it — usually by logging and stopping.

An AI agent using MCP can reason about failures and adapt. If create_article fails because a required field is missing, the AI can re-read its previous output, identify what is missing, and retry with the corrected parameters. If upload_media fails because the image URL is unavailable, the AI can try an alternative source or inform the user rather than crashing. This adaptive error recovery is impossible with deterministic scripts but natural for language models working through MCP.

Composability: Chaining Tools Together

One of MCP's most powerful properties is that the AI can compose multiple tools together to accomplish complex tasks that no single tool handles end-to-end. Here is an example workflow:

User: "Move all articles tagged 'draft' to the 'Review' category 
       and update their state to unpublished."

AI plan:
1. list_tags() → find the ID for the 'draft' tag
2. search_articles(tag_id=X) → find all articles with that tag
3. list_categories() → find the ID for the 'Review' category
4. For each article:
   a. update_article(id, catid=Y, state=0)
5. Report: "Updated 7 articles to the Review category."

Writing this as a traditional script would take a developer 30-60 minutes. As an MCP prompt, it takes 10 seconds. The AI handles the multi-step planning, the iteration, and the error checking.

When to Use REST API Directly (Not MCP)

MCP is the right tool for AI-driven workflows, but direct REST API access remains better for several scenarios:

High-Volume Batch Operations

If you need to process 10,000 articles — checking each for a specific condition and updating it — a direct API script with proper rate limiting and parallelism will be faster and more reliable than an AI agent. The AI's interpretive overhead adds latency that compounds at scale.

Deterministic Integrations

If Joomla is one node in a data pipeline — receiving webhooks from an e-commerce platform and creating articles from product data — a direct API integration is more appropriate. The logic is fixed; there is nothing for an AI to interpret or decide.

System-to-System Automation

When another software system is the client (not a human or an AI agent), REST is the right interface. MCP is specifically designed for AI model clients, not for machine-to-machine integrations.

The Architecture That Combines Both

The most capable Joomla setups use both layers appropriately:

┌─────────────────────────────────────────────────────────┐
│                    Use Cases                            │
├─────────────────────┬───────────────────────────────────┤
│  AI-Driven (MCP)    │  Deterministic (Direct API)       │
├─────────────────────┼───────────────────────────────────┤
│  Content creation   │  Batch imports                    │
│  SEO audits         │  Webhooks                         │
│  Maintenance tasks  │  System integrations              │
│  Content QA         │  Scheduled bulk updates           │
│  Site management    │  Data pipelines                   │
└─────────────────────┴───────────────────────────────────┘
         ↓                           ↓
    MCP Server              Direct REST API calls
         ↓                           ↓
         └─────────────────────────┘
                      ↓
              Joomla REST API
                      ↓
              Joomla Database

Both paths end at the same Joomla REST API. The difference is only in the client layer above it.

What This Means for Joomla Developers

If you have invested time understanding Joomla's REST API — the endpoint structure, authentication, response format, and filtering — that knowledge transfers directly to MCP development. Building an MCP server is essentially writing a structured declaration of your existing API knowledge, plus the routing code that maps tool calls to API calls.

The learning curve for MCP is shallow for Joomla API developers. The new concept is tool schemas and the MCP SDK — the Joomla-specific knowledge you already have remains the foundation. And once your MCP server is running, you gain a dramatically more capable interface to your Joomla site than direct API scripts alone can provide.

MCP does not make the REST API obsolete. It makes it AI-accessible — which, as AI tools become the primary way people interact with complex software, is increasingly the property that matters most.