Salesforce Hosted MCP Servers: exposing your Apex and Flows to external agents

Until this year, every Model Context Protocol story in Salesforce ran one direction. Your agent, or a local dev tool, reached out to somebody else’s MCP server. Hosted MCP Servers, generally available since April 2026, run the other way. Your org is the server now, and an external agent, Claude, ChatGPT, Cursor, or your own client, calls into it.

That reversal is the whole point, and it changes who has to build what. You don’t write a REST wrapper and a custom connector so an outside agent can update a record anymore.

You mark an Apex method global, register it as a tool on a hosted server, and the agent calls it over an authenticated connection that Salesforce hosts and scales for you. The business logic you already have becomes agent-callable without new integration middleware.

I’ll say the thing I’d say across a desk first. This is the cleanest way to let an external AI act inside your org, and it’s also the easiest place to hand an agent more power than you meant to. The auth model and the permission enforcement are the parts to get right before you turn a server on, not after.

What “hosted” buys you

We wrote about connecting Agentforce to an MCP server as the client side: your agent consuming external tools. We covered the local DX MCP server that drives your org from an IDE, and the Data 360 headless MCP server for querying unified data from Claude. If you want the protocol itself explained, the enterprise MCP primer is the place to start.

Hosted MCP Servers are none of those. Salesforce runs the server inside its own security perimeter. There’s nothing to provision, no uptime to manage, no container to patch. You enable a server in Setup and it’s live. That matters because the alternative, self-hosting an MCP server that proxies into Salesforce, means you own an internet-facing service that holds org credentials, and your security team owns its review.

The trade is control for convenience. A hosted server exposes what the platform lets it expose, in the shape the platform defines. You give up the freedom to write arbitrary server code. For most teams that’s the right trade, because the arbitrary server code was the liability.

The auth model is External Client Apps, and Connected Apps won’t work

Here is the first place people get stuck. A hosted MCP server authenticates through an External Client App, not the Connected App you’ve reached for every other integration. Reach for a Connected App out of habit and the connection simply won’t establish.

You need System Administrator rights to create the External Client App in Setup, and you configure a callback URL specific to whichever client you’re wiring up, because the callback differs between Claude, ChatGPT and a custom client.

The flow is OAuth 2.0 with PKCE, so there’s no client secret sitting in a config file waiting to leak. The agent completes an authorization-code exchange, and the tokens it gets are scoped and refreshable.

Add exactly two OAuth scope groups to the app and no more:

• mcp_api, described in Setup as “Access Salesforce Hosted MCP Servers”
• refresh_token, offline_access, “Perform requests at any time”

Resist the urge to add full or api because it’s faster. The scope you grant is the ceiling on what any agent connecting through that app can reach. This is the same discipline we argued for in OAuth token exchange for AI agents: the narrowest scope that still lets the tool do its job.

What you can expose, and the global-vs-public trap

A custom server turns existing org assets into tools without connector code. Five kinds of thing qualify:

• Apex Invocable Actions
• @AuraEnabled Apex methods
• Apex REST endpoints
• Flows
• Named Queries

That list is broad enough that most orgs already have the logic they’d want to expose. The catch is in the Apex. A method you expose as an MCP tool has to be declared global, not public, because MCP tool discovery reads the global signature. This trips up teams constantly, because public is the default reflex and the method compiles fine, it just never shows up as a tool.

Here’s a minimal invocable action written correctly for exposure:

global with sharing class GetOpenOrders {

    global class Request {
        @InvocableVariable(required=true label='Account Id')
        global Id accountId;
    }

    global class Result {
        @InvocableVariable global String orderNumber;
        @InvocableVariable global Decimal amount;
        @InvocableVariable global String status;
    }

    @InvocableMethod(
        label='Get open orders for an account'
        description='Returns open orders so an agent can summarise account status.')
    global static List<List<Result>> run(List<Request> requests) {
        List<Result> out = new List<Result>();
        for (Order o : [
            SELECT OrderNumber, TotalAmount, Status
            FROM Order
            WHERE AccountId = :requests[0].accountId AND Status = 'Activated'
            WITH USER_MODE
            LIMIT 200
        ]) {
            Result r = new Result();
            r.orderNumber = o.OrderNumber;
            r.amount = o.TotalAmount;
            r.status = o.Status;
            out.add(r);
        }
        return new List<List<Result>>{ out };
    }
}

Two design notes on that class. The description on the method isn’t cosmetic. It’s what the agent reads to decide whether to call this tool, so write it the way you’d write a docstring for a colleague who has never seen your data model.

The method also absorbs the interpretation: it returns three named fields, not a raw SObject dump. Give the agent insight, not rows to guess at. A tool that returns the whole record forces the model to reason over noise and burns tokens doing it.

You register the server and its tools in Setup under MCP Servers, attach the actions and flows you want, and connect the External Client App. There’s no build step beyond that.

Permissions are enforced as the running user, which is the safety net and the sharp edge

The reassuring part: the agent acts strictly within the connecting user’s permissions. CRUD, field-level security and sharing all apply. An agent connected as a support rep can’t read the payroll object the rep can’t read. That WITH USER_MODE in the SOQL above isn’t decoration; it makes the query honour the running user’s FLS and sharing rather than running in system context.

The sharp edge is the flip side. The agent has exactly the access of whoever authorized it, and an agent is tireless and scriptable in a way a person at a keyboard isn’t.

If you connect an integration user with a wide permission set out of convenience, you’ve handed an external model that whole surface. Connect a real, least-privilege user, and treat the External Client App’s scope and the connecting user’s profile as one combined blast radius.

This is where a hosted MCP server differs in feel from the headless Agent API, which wraps a governed agent you designed. Here the external model does the reasoning and your tools are the actions. The guardrail isn’t a topic you scoped; it’s the permission set on the user and the tool list on the server. Design both as if the model will call every tool in every order, because eventually it will try.

The credit meter nobody mentions in the demo

A hosted MCP server has no separate SKU and no per-call MCP charge. It’s available on Enterprise Edition and above. That sounds free, and the connection itself is. What isn’t free is what the tools do.

When an agent calls a tool that runs an Agentforce action, you’re on the Flex Credit meter like any other action: a standard action is 20 Flex Credits, and Flex Credits list at $500 per 100,000, so roughly $0.10 an action. Call a tool that grounds against Data 360 and you’re metering Data 360 consumption on top. The MCP layer is a doorway; the room behind it has a meter.

The reason this bites is that an external model decides how many tools to call. A well-scoped agent you built resolves a request in a handful of actions. A general-purpose model exploring your tool list to answer a vague prompt can chain far more, and every chain link is a metered event. Turn on Digital Wallet alerts before you expose a server to a chatty client, not after the first surprising invoice. The economics here are the same lesson as agent design generally: your tool surface is your bill.

Where a hosted server is the right call, and where it isn’t

Reach for a hosted MCP server when an external agent needs to take governed action in your org and you don’t want to own a proxy service. Letting a developer’s Cursor session read and update records through the org’s own permission model, giving a Claude workflow a handful of safe, well-described tools, exposing a Named Query so an external assistant can answer questions from live data: these fit.

Don’t reach for it when the real need is a Salesforce-native agent talking to an outside system. That’s the client direction, and it’s still Agentforce consuming an external MCP server or MuleSoft brokering the API actions. And don’t use it to move bulk data. MCP tools are for discrete, reasoned actions, not for shovelling a million rows; that’s a job for zero-copy sharing or the Bulk API.

The mental model that keeps this straight: a hosted MCP server publishes a small, sharp set of your org’s verbs to the outside world, under a named user’s permissions, on a meter. Keep the verb list short, the descriptions honest, the user least-privileged, and the alerts on. Do that and it’s the most useful new integration surface Salesforce has shipped in a while. Skip it and it’s the fastest way to give a language model the keys to a system it doesn’t understand.

Understanding the basics

What is a Salesforce Hosted MCP Server?

It’s a Model Context Protocol server that Salesforce hosts inside its own security perimeter, generally available since April 2026 on Enterprise Edition and above. You enable it in Setup and expose existing org assets, Apex Invocable Actions, @AuraEnabled methods, Apex REST endpoints, Flows and Named Queries, as tools that external AI clients like Claude, ChatGPT or Cursor can call, with no server for you to provision or maintain.

How does authentication work for a hosted MCP server?

Through an External Client App, not a Connected App, using OAuth 2.0 with PKCE. A System Administrator creates the app in Setup, sets a client-specific callback URL, and grants exactly two scope groups: mcp_api (Access Salesforce Hosted MCP Servers) and refresh_token, offline_access. The connecting agent then acts within that user’s permissions, with CRUD, field-level security and sharing all enforced.

Why isn’t my Apex method showing up as an MCP tool?

The most common reason is that the method is declared public instead of global. MCP tool discovery reads the global signature, so an invocable method, its request class, and its variables all need to be global to be exposed. The method compiles and runs fine as public; it just never appears as a callable tool.

Does a hosted MCP server cost extra?

There’s no separate MCP SKU and no per-call charge for the connection itself. You pay for what the tools do: an Agentforce action runs on the Flex Credit meter (20 credits, about $0.10, for a standard action), and a tool that grounds against Data 360 meters Data 360 consumption. Because an external model decides how many tools to chain, watch usage in Digital Wallet from day one.

---

Thinking about opening your org’s logic to external agents without standing up a proxy service or over-granting scope? Talk to us about your integration architecture. Getting the auth model, the tool surface and the permission blast radius right is exactly the work we do.