This is the final blog in the series about Headless MuleSoft for developers. Part one mapped the three surfaces. Part two explained how Skills make agents reliable. Part three showed what headless operations looks like in practice. Now: let’s get you connected — and see everything you just read come to life in your own terminal.
The MuleSoft Platform MCP Server lets you manage your Anypoint control plane in plain English — and in this step-by-step guide you’ll connect it to Claude Code, right from your terminal. You can list your APIs, apply a policy, and check what’s eating your LLM token budget without ever leaving it. Same identity, same permissions, same governance as the Enhanced MuleSoft Experience UI. No context switching.
This tutorial walks through it end to end.
Heads up on naming. There are two MuleSoft MCP servers. The DX MCP Server helps you build Mule apps from your IDE. The Platform MCP Server — the one we’re using here — lets you discover, govern, and monitor your APIs, agents, MCP servers, and LLMs across the org. We want the Platform one.
What you’ll need
- An Anypoint Platform account. Don’t have one? Create a free trial at anypoint.mulesoft.com — it’s enough to follow along.
- Claude Code installed, with a paid Claude plan. Claude Code requires a Pro, Max, Team, or Enterprise subscription, or a pay-as-you-go Anthropic Console (API) account — the free plan doesn’t include Claude Code access. Confirm it runs:
claude --version
- Permission to create a connected app in your Anypoint org (trial accounts have this).
That’s it. The Platform MCP Server is a remote server — there’s nothing to install or run locally. You point Claude Code at a URL and authenticate over OAuth.
Step 1 — Create a connected app in Anypoint Platform
The MCP server authenticates as you, through a connected app. Claude Code’s access is bounded by your own Anypoint permissions — it can do what you can do, nothing more.
- In Anypoint Platform, go to Access Management → Connected Apps → Create app.
- Name — give it something like claude-code-platform-mcp.
- Type — choose App acts on behalf of a user (not “App acts on its own behalf” — we want your identity and permissions, and only the user-behalf type supports the OAuth login Claude Code uses).
- Grant types — check Authorization Code and Refresh Token. Both are required: the server uses the authorization-code OAuth flow and refreshes your token so you’re not re-authenticating constantly. Leave Password and JWT Bearer unchecked.
- Website URL — required, but it’s just informational. Any valid URL works (e.g. https://docs.mulesoft.com).
- Redirect URIs — this is required. Claude Code completes OAuth on a local callback port, and MuleSoft requires the redirect URI to be pre-registered, so pick a port now and enter http://localhost:8976/callback (8976 is arbitrary — any free port works, just remember it; you’ll reuse it in Step 2). Type it in and press Add. (You can edit this later — just reopen the connected app and update the redirect URI if you want a different port.)
- Who can use this application? — leave it on Members of this organization only.
- Scopes — click Add Scopes and add just these two:
- Full Access
- Background Access
- Click Save. Then copy the Client ID and Client Secret.
Why Full Access — and not granular scopes?
Scopes are the #1 thing people get wrong here, and with Claude Code there’s a catch worth knowing up front: Claude Code’s OAuth flow doesn’t work with granular scopes yet. When it authenticates, it requests the all-access full scope (plus offline_access) — it has no way to ask for a narrower set. So if you grant the connected app only the granular tier scopes (Exchange Viewer, Monitoring Viewer, API Manager Administrator, and so on), Anypoint rejects the login with an invalid_scope error before you ever reach a tool, because that granular set is a subset of what Claude Code asks for.
The fix is to grant the connected app Full Access and Background Access:
| Scope to add | What it does |
| Full Access | Grants the all-access full scope Claude Code’s OAuth flow requests — covers every tool: APIs, monitoring, policies, governance, cost, gateways, business-group switching, and more |
| Background Access | Required for the OAuth handshake itself — lets the server authenticate you and refresh your token |
This is broader than least-privilege, and it diverges from the granular per-tool scopes the MuleSoft docs describe — but until Claude Code can request a narrower scope, Full Access is what makes the connection work. If you need tighter scoping, use a client that lets you specify scopes (e.g. the Claude Desktop custom-connector flow).
Full Access is still bounded by you. As the tooltip on the scope notes, Full Access grants “full access to all data accessible by the authorizing user” — it’s every scope except offline_access, but only within what your own Anypoint account can already reach. It doesn’t elevate you past your own permissions. So if you want to keep this connection tightly scoped, the move isn’t narrower OAuth scopes (Claude Code can’t request them) — it’s a narrower user: create a dedicated Anypoint user with only the access you want Claude Code to have, then authenticate as that user. Full Access on a limited account is still limited. Do this carefully — the connection can do anything that user can do.
With the connected app saved and your Client ID, Client Secret, and callback port in hand, you’ve got everything Anypoint needs to give you. The rest happens in your terminal — let’s point Claude Code at the server and connect.
Step 2 — Add the MuleSoft MCP server to Claude Code
The Platform MCP Server lives at https://omni.mulesoft.com/mcp — the global US endpoint, which we’ll use for this guide.
On a different control plane (EU, CA, JP, IN)? Swap in your regional host (e.g. https://eu1.omni.mulesoft.com/mcp) — the full list is in the Getting Started docs.
Run the claude mcp add command below in your terminal, filling in the Client ID and Client Secret from your connected app. We pin the OAuth callback to the same port you registered in Step 1 with –callback-port:
MCP_CLIENT_SECRET=<YOUR_CLIENT_SECRET> \ claude mcp add --transport http mulesoft-platform \ https://omni.mulesoft.com/mcp \ --client-id <YOUR_CLIENT_ID> \ --client-secret \ --callback-port 8976
You’ll see a confirmation that the server was registered:
Added HTTP MCP server mulesoft-platform with URL: https://omni.mulesoft.com/mcp to local config File modified: /Users/<you>/.claude.json [project: /path/to/your/project]
A few notes:
- The bare –client-secret flag is required even when you set MCP_CLIENT_SECRET. Claude Code only reads the env var if –client-secret is present on the command line — the flag takes no value (it tells the CLI to read MCP_CLIENT_SECRET, or to prompt you if the var isn’t set). Leave the flag off and the secret is silently dropped: registration still “succeeds,” but the OAuth token exchange later fails with a bare HTTP 401: … Unauthorized. Passing the secret via the env var (rather than typing it after a flag) also keeps it out of your shell history.
- –callback-port must match the redirect URI you registered in Step 1. We used 8976 (http://localhost:8976/callback), so we pass 8976 here. This is the step that trips most people up: if the port and the registered redirect URI don’t match, the OAuth handshake fails.
- mulesoft-platform is just the local name for the server; call it whatever you like.
- This adds the server for the current project only. By default claude mcp add uses local scope, so the server is available in this repo and nowhere else (notice the [project: …] in the output above). To make it available across all your projects, add -s user after –callback-port 8976.
Step 3 — Authenticate and verify
Start Claude Code in your project:
claude
Check that the server registered:
/mcp
You should see mulesoft-platform listed, with a ⚠ needs authentication badge — it hasn’t completed OAuth yet:
Manage MCP servers 1 server Local MCPs (/Users/you/.claude.json [project: /path/to/your/project]) ❯ mulesoft-platform · ⚠ needs authentication
Select mulesoft-platform to open its detail view, which shows the server status, URL, and config location, along with a couple of actions:
Mulesoft-platform MCP Server Status: ⚠ needs authentication Auth: ✗ not authenticated URL: https://omni.mulesoft.com/mcp Config location: /Users/you/.claude.json [project: /path/to/your/project] ❯ 1. Authenticate 2. Disable
Choose Authenticate. Claude Code opens your browser to complete the Anypoint OAuth login — sign in, approve the access (you’ll see an Authorize App screen requesting Full Access and Background Access — click Grant access), and you’ll be redirected back to the local callback, which confirms:
Authentication Successful You can close this window. Return to Claude Code.
Back in Claude Code, /mcp confirms the connection:
Authentication successful. Connected to mulesoft-platform.
And the server list now shows the badge flipped to ✓ connected, along with the number of tools loaded:
Manage MCP servers 1 server Local MCPs (/Users/you/.claude.json [project: /path/to/your/project]) ❯ mulesoft-platform · ✓ connected · 66 tools
From the terminal you can also confirm the server is registered:
claude mcp list
The Platform MCP Server requires a login tool call before any other tool runs, but Claude handles that for you automatically once OAuth succeeds — you don’t invoke it by hand.
Step 4 — Manage your platform: your first commands
Now the fun part. Talk to your platform in plain English. Here are three prompts that together tell a complete discover → observe → govern story.
Discover what you have
You: List the APIs in my organization.
Behind the scenes Claude calls list_apis. Try follow-ups like “search my portfolio for anything related to payments” (search_portfolio_services) or “what MCP servers are registered in my org?” (list_mcp_servers).
See what’s costing you
You: Show me a cost overview, and tell me which instances are consuming the most tokens.
This is the question every team is asking right now. Claude pulls fetch_cost_overview and fetch_cost_instances and summarizes where your LLM spend is going. Ask it to “recommend ways to cut cost” and it’ll reach for fetch_cost_optimization_recommendations.
Check health, then govern
You: Give me a monitoring overview for my APIs and flag anything underperforming.
That’s fetch_monitoring_overview + show_observability_performance. And you can close the loop:
You: Apply a rate-limiting policy to my Orders API instance.
Claude will use prepare_policy_creation / get_policy_template_form to gather the parameters, then apply_policy_to_instance to enforce it — the same governance action you’d take in API Manager, done from your terminal.
Why this matters
It’s tempting to file this under “neat AI trick,” but the real story is consistency. The actions you just ran from Claude Code are scoped to your user and org (your permissions come from Anypoint Access Management, via the connected app you created) and enforced by the same governance model as the enhanced experience. There’s no parallel set of rules for the AI surface. Whether you manage your platform through that UI, through a headless API, or conversationally from your terminal, governance travels with you.
That’s the whole bet behind MuleSoft’s headless and agentic direction: not more tools, but one consistent control plane you can reach from wherever you already work — and for a lot of us, that’s the terminal.
Frequently asked questions
What is the MuleSoft Platform MCP Server?
It’s a remote Model Context Protocol (MCP) server from MuleSoft that lets AI clients like Claude Code discover, govern, and monitor your Anypoint platform — APIs, agents, MCP servers, and LLMs — in natural language. It’s distinct from the MuleSoft DX MCP Server, which is for building Mule apps from your IDE.
Can I use the MuleSoft Platform MCP Server with Claude Code?
Yes. It’s a remote HTTP MCP server, so you add it with claude mcp add –transport http, point it at your regional omni.mulesoft.com/mcp endpoint, and authenticate over OAuth. No local install required.
Do I need a paid Anypoint account to try this?
No. A free trial at anypoint.mulesoft.com is enough to create a connected app and follow this tutorial.
Why isn’t the MCP server working, or why does authentication fail with invalid_scope?
Almost always a scope problem or a redirect-URL mismatch. For scopes: Claude Code’s OAuth flow requests the all-access full scope and can’t request granular ones, so the connected app needs Full Access and Background Access (see Step 1) — a granular-only app fails the login with invalid_scope. For the redirect: confirm the connected app’s registered redirect URL matches the –callback-port you used in Step 2.
Is this the same as connecting MuleSoft to Claude Desktop?
The platform and tools are the same — only the client differs. Claude Desktop uses a GUI “Custom Connector”; Claude Code uses the claude mcp add CLI command shown here.
Where to go next
That’s the full series. You started with a map of three surfaces. You learned the reliability layer underneath them. You saw what headless operations looks like in production. And now you’re connected.
One platform. No console required. Available from wherever your team — and your agents — already work.
- Govern the agentic layer: the cost and policy tools you just used are the same surface Omni Gateway uses to federate governance across API, MCP, LLM, and agent traffic — even across gateways you don’t own. A natural follow-on.
- Build, don’t just manage: check out the DX MCP Server to scaffold and deploy Mule apps from your IDE in natural language.
- Go deeper on the catalog: the MuleSoft Developer Hub exposes the full set of platform APIs, Skills, and MCP servers built for agents to operate.
Tool names, scopes, and endpoints can change as the product evolves — if a command behaves differently than described, check the latest Platform MCP Server docs for the current details.
