This is the first article in a four-part blog series about Headless MuleSoft for developers covering how to choose, build on, and operate MuleSoft from outside the platform user interface such as Slack, Claude Code, AI IDE, or wherever your team already works.
MuleSoft now exposes Anypoint Platform through three distinct surfaces designed for AI agents and automation. If you’ve seen the announcements, you know about the Developer Hub, the Platform MCP (Model Context Protocol) Server, and IDE Skills. What you probably don’t know is which one you should actually use.
The short version: Building a custom agent? Start with the Developer Hub. Working interactively in your IDE? Connect the MCP Server. Writing Mule code? Install Skills.
They all touch the same underlying platform. They overlap in places. But they’re built for different workflows, different architectures, and different problems. Picking the wrong one means you’ll either over-engineer a simple task or hit a ceiling when you need real flexibility.
Here’s how to choose:
3 surfaces at a glance
- Developer Hub (dev-portal.mulesoft.com) is a machine-readable catalog of 36 OpenAPI specs, 28 multi-step Skills, and 2 MCP server definitions. The catalog itself is public; your agent fetches registry.json and resolves URNs to raw spec files with no auth. To call the APIs those specs describe, your agent authenticates with a Bearer token and hits REST endpoints directly. You own the control flow entirely
- Platform MCP Server (omni.mulesoft.com/mcp) is a remote MCP server that exposes ~70 tools for service discovery, governance, monitoring, and cost management. You connect it to an MCP client (Claude, Cursor, Windsurf) and interact conversationally. The server handles tool routing, pagination, and context management
- IDE Skills (.a4drules/skills/ or installed via npx skills add mulesoft/mulesoft-dx/skills/mule-development) are structured instruction sets that an AI coding assistant loads on demand. They guide multi-step workflows for both Mule development (building integrations, configuring connectors, running diagnostics) and platform operations (securing APIs, managing portals, setting up scanners). They work inside MuleSoft Vibes, Claude, Cursor, and other supported agents.
Now, let’s take a closer look at when to use which.
1. Developer Hub: Custom agents and pipelines
The Developer Hub is raw materials. It gives you OpenAPI specs and lets you decide how to call them, in what order, with what error handling, and in what execution environment.
Choose it when:
- You’re building a custom agent (LangChain, CrewAI, your own framework)
- You want programmatic access to APIs the MCP Server doesn’t expose as tools
- You need to control retry logic, caching, batching, or parallelism
- You’re integrating Anypoint operations into a larger orchestration pipeline
- You want your agent to stay in sync with platform changes without manual updates
What you get:
- Full API surface (36 APIs across 15 categories)
- OpenAPI 3.0 specs your framework can ingest natively
- x-origin annotations that tell your agent how to chain API calls (which parameter values come from which other API’s response)
- Skills as documented workflow recipes your agent can follow step by step
- No intermediate abstraction layer between your code and the platform
What you give up:
- You handle auth token lifecycle yourself
- You parse specs, resolve parameter dependencies, and manage state
- No conversational interface; you write the orchestration logic
Example: You’re about to script the steps for securing a new API with rate limiting. Before writing that automation from scratch, you ask your agent to check the Hub. It searches registry.json, finds the secure-api skill with a pre-built 7-step workflow (publish to Exchange, create an API Manager instance, deploy to gateway, browse the policy catalog, apply the policy), and follows that instead of you manually chaining API calls.
2. Platform MCP Server: Conversational access
The MCP Server is a curated, governed interface. Someone already decided which operations to expose as tools, how to paginate results, and what context to maintain between calls. You ask questions in natural language; the AI assistant picks the right tool.
Choose it when:
- You’re working in Claude, Cursor, or another MCP client
- You want to explore your platform state conversationally (“show me non-compliant APIs,” “what’s my token spend this month”)
- You need quick answers without writing code or checking the UI
- You want governed access (the server enforces what’s available through scopes)
- Multiple team members need the same capabilities without each building an integration
What you get:
- ~70 pre-built tools covering discovery, governance, monitoring, cost, and provisioning
- Conversational interface; no code required for ad hoc queries
- Cross-tool context (the server maintains your active business group, environment, and provider)
- OAuth-based auth with connected apps (set up once, reuse across sessions)
What you give up:
- You can’t call APIs the server doesn’t expose as tools
- You don’t control execution flow; the AI assistant decides tool ordering
- Not suitable for batch operations or CI/CD (it’s interactive, not scriptable)
- Tool surface can change between server versions
Example: You’re debugging a production issue. You ask Claude: “Which APIs in production have the highest error rate?” It calls fetch_monitoring_drill_down. You follow up: “Are any of those non-compliant with our governance standards?” It calls fetch_governance_services and correlates. No pipeline needed; you got your answer in two questions.
3. IDE Skills: Guided Mule development
Skills are contextual instruction sets that cover both Mule development and platform operations. Think of them as an experienced colleague’s runbook, loaded into your AI assistant only when relevant. About half focus on building and configuring Mule apps; the other half handle platform tasks like securing APIs, managing API Experience Hub portals, and setting up agent scanners.
Choose them when:
- You’re building or modifying Mule integrations in MuleSoft Vibes or your IDE
- You want guided, multi-step workflows (not just raw API access)
- You need the AI to follow MuleSoft-specific best practices (connector config, error handling, DataWeave patterns)
- You’re developing custom Flex Gateway policies with PDK
- You want a guided path for platform tasks like securing an API or setting up a scanner
What you get:
- 28 skills covering Mule development (build flows, manage configs, develop PDK policies) and platform operations (secure APIs/agents/MCP servers, manage portals, run scanners)
- Workflow-level guidance: the skill tells the AI what to do in what order, with validation
- Works across multiple agents (MuleSoft Vibes, Claude, Cursor, Cline, Codex)
- Installable per-project or globally; committable to your repo
What you give up:
- Requires an IDE or coding agent context (not for standalone automation)
- Skills guide the AI’s behavior; they don’t execute API calls on their own (the AI uses its available tools, whether that’s Bash, MCP, or direct HTTP calls, to carry out each step)
Example: You tell Claude: “Build me a Salesforce-to-Slack integration.” The build-mule-integration skill activates. Before writing a single line of XML, it searches Exchange for the right connectors (no hardcoded versions from memory), describes their operations, selects a trigger pattern, generates configuration files with externalized credentials, builds the flow, and verifies it compiles with mvn clean package. The skill enforces standards you’d forget: never assume a connector version, always add doc:description to canvas components, always validate prerequisites first.
Comparison table
| Developer Hub | Platform MCP Server | IDE skills | |
|---|---|---|---|
| interface | REST (raw HTTP) | MCP protocol (tool calls) | AI assistant instructions |
| Auth | None to discover; Bearer token to call APIs | OAuth connected app | Inherits from IDE/CLI auth |
| Discovery | registry.json + URN resolution | Built-in tool list | Skill loads when task matches |
| Execution | Your code calls APIs | AI assistant calls tools | AI follows skill steps + calls MCP tools |
| Scope | Full platform (36 APIs) | Curated subset (~70 tools) | Mule dev + platform operations (28 skills) |
| Best for | Custom agents, orchestration pipelines | Interactive exploration, ad hoc queries | Building Mule integrations |
| Control | You own everything | Server owns tool routing | Skill owns workflow; you own the code |
| Requires code | Yes | No | No (but you’re writing Mule code) |
They compose, not compete
These aren’t competing choices. They layer:
- Skills reference Hub APIs: The platform operations capabilities (like secure-api or setup-agent-scanner) include api: urn:api:api-manager in their step definitions, chaining Hub APIs together. For these skills, the Hub is the ingredient list; the skill is the recipe
- The MCP Server is listed in the Hub: The registry includes kind: “mcp” entries for both the Platform and DX MCP servers. An agent that starts at the Hub can discover and wire up MCP servers dynamically
- Skills guide, tools execution: A skill like build-mule-integration guides the AI’s decision-making, but the actual file creation happens through whatever tools the agent has (Bash, file editors, MCP tools). A skill like secure-api tells the agent which API operations to call and in what order. Skills are the brain; the agent’s tools are the hands
A realistic workflow uses all three:
- A custom agent uses Hub-discovered APIs to audit org state across multiple business groups (automated, no human in the loop)
- A developer uses the MCP Server in Claude to investigate issues surfaced by that audit (interactive, conversational)
- That same developer uses Skills when building the fix (guided, IDE-native)
How the 3 MuleSoft AI surfaces layer together
MuleSoft’s three AI surfaces operate at different altitudes: the Hub provides raw API specs, the MCP Server provides governed conversational access, and Skills provide guided multi-step workflows. A year ago, “automate Anypoint Platform” meant one thing: call REST APIs and handle everything yourself. Now there are three layers, each serving a different need:
- Hub = raw capability (specs, schemas, the full surface)
- MCP servers = governed, conversational access (curated tools, stateful context)
- Skills = guided workflows (multi-step recipes for development and platform tasks)
The layer you pick depends on how much control you want versus how much orchestration you want handled for you. And because they compose, you don’t have to commit to just one.
Get started today
To get started, browse the Developer Hub catalog, connect the Platform MCP Server, or install MuleSoft Skills in your IDE.
You now have the map. Once you’ve picked your headless surface, how do you make the agents running on it actually reliable? Multi-step workflows fail more often than not when an agent is making it up as it goes. That’s the problem skills are designed to solve. Skills are structured, ‘fetchable’ workflow recipes that tell agents not just what to call, but in what order, with what data, and where the potential pitfalls are.
