Hey folks, Abhi here!

I’ve been spending a lot of time with Salesforce Hosted MCP Servers and Agentforce lately. And the one feature that genuinely made me go “oh, that’s clever” wasn’t a fancy agent or a big AI model. It was a humble little thing called Named Query API.

If you’re an admin who’s been wondering how to let AI agents read your Salesforce data safely, without handing them the keys to the entire org and without begging a developer for an Apex class, this one’s for you.

So what is a Named Query?

Simple version: it’s a SOQL query that you save in Setup, give a name, and Salesforce turns it into a reusable API.

That’s it. You define SOQL queries from which you can then create custom agent actions for agents, and expose them as REST APIs for use by external applications. Write the query once, use it everywhere.

The magic is in the parameters. Instead of hardcoding a value, you use a colon bind like :accountname. Whoever calls the query (an integration, an Agentforce agent, or an MCP client like Claude) only supplies that value. They can’t change the query itself.

Why should admins care?

Think about how we’ve traditionally given agents access to data. For Agentforce agents, data access is typically handled through tools such as autolaunched flows or Apex classes. With an autolaunched flow, you can use a Get Records element to retrieve data and return it as flow output.

Nothing wrong with that. But building a whole autolaunched flow just to fetch a record and its related list? That’s a lot of clicks for a read operation. And the Apex route means a developer, a test class, and a deployment.

With Named Query, all you need to do is to write the SOQL query using a dedicated UI instead of creating a flow or writing an Apex class.

The other big win is control. If you give an AI agent a generic “run any SOQL” tool, it’ll happily write its own queries across whatever objects the user can see. That’s flexible, but unpredictable. A Named Query is the opposite: fixed objects, fixed fields, fixed filters. You decide exactly what the agent gets to see, and you test it once.

An example: Account 360 in one call

Say your sales team keeps asking an agent things like “give me a quick summary of Acme Corp.” To answer well, the agent needs the Account, its key Contacts, and its open Opportunities.

Here’s a Named Query called AccountSummary that does exactly that:

sql

SELECT Id, Name, Industry, Type, AnnualRevenue, Owner.Name,
       (SELECT Id, Name, Title, Email FROM Contacts LIMIT 5),
       (SELECT Id, Name, StageName, Amount, CloseDate
        FROM Opportunities WHERE IsClosed = false)
FROM Account
WHERE Name = :accountname
LIMIT 1

See those two subqueries? That’s the part I love. One call returns the Account, its top Contacts, and its open pipeline together. The agent doesn’t need to make three separate lookups and stitch things together, and it gets clean, complete, related data in one response. That’s exactly what it needs to give a useful answer instead of a half-baked one.

How to create one (step by step)

Here’s the flow in Setup:

1. Search for Named Query API in Setup and click New.
2. Give it a label and API name. Heads up: the API name must begin with a letter and can contain only alpha-numeric characters, so no underscores.
3. Enter the API version.
4. Write a really good description. I’ll come back to why this matters so much.
5. Paste your SOQL with your :parameter bind in the WHERE clause.
6. Click Validate. The API endpoint is automatically created and displayed, something like /services/data/v65.0/named/query/AccountSummary?accountname=<name>.
7. Add a description for each parameter.
8. Save.

If you want to use it as an Agentforce action, there’s an extra step. On the User Interface page, select Enable Salesforce Platform REST API, Named Query for Agent Actions (Beta). After you enable the beta and create a Named Query API, it’s automatically displayed in Setup > API Catalog. Manually activate Named Query APIs in the API Catalog to make them available as agent actions.

Note that the agent action piece is still labeled beta in the docs, so check your org’s current release notes before building anything production-critical on it.

Plugging it into an MCP server

This is where it gets fun for anyone experimenting with Claude, ChatGPT, or other AI clients. Salesforce Hosted MCP Servers let you build custom servers, and custom tools let you expose Apex Invocable Actions, @AuraEnabled methods, Apex REST methods, Flows, and Named Queries as MCP tools without writing connector code.

You build a custom server in Setup, add your Named Query as a tool, activate the server, and connect your AI client to the server URL. From there, the AI client sees your query as a tool it can call, complete with the description and parameters you wrote.

Security: the part admins will love

Named Queries don’t bypass your security model. With hosted MCP, your existing permissions automatically apply — CRUD, FLS, sharing rules, and all the other controls you’ve already mastered. Every transaction runs as the authenticated user, without anonymous service accounts or a new security model to learn.

For Agentforce, the same idea applies: you’ll need to ensure that the user for whom the agent will invoke the Named Query API is authorized with read access to the object being queried.

So if a sales rep can’t see the AnnualRevenue field, the agent working on their behalf can’t either. No new permission model to learn. Your profiles, permission sets, and sharing rules just keep doing their job.

Gotchas to watch for

1. Descriptions are your prompt. This is the big one. The AI decides when to use your query based on its description. The docs say it directly: if you intend to use the Named Query API as an agent action, AI agents will use it to understand when it’s optimal to select this action. A lazy description like “gets account” won’t cut it. Write something like “Returns an Account’s summary by name, including industry, owner, top contacts, and open opportunities.”

2. Parameters only work in simple places. In a WHERE clause, use parameters in simple expressions such as name = :name, and with the logical operators AND, OR, NOT. Things like IN expressions don’t support parameters, so plan your filters accordingly.

3. Limiting results has a naming rule. If a LIMIT clause in the top-level query has a colon parameter, it must be named maxrecords. Easy to miss, annoying to debug.

4. Watch out for name-based lookups. Filtering on Name works great in a demo, but in real life? Two Accounts called “Acme” returns ambiguous results. A user typing “Acme Inc” when the record says “Acme Corporation” returns nothing. Your agent needs to handle both cases gracefully, ideally by asking for something unique instead of guessing. Consider a second Named Query keyed on a unique field like an external ID or Account Number, and describe both clearly so the agent picks the right one.

5. Always add a LIMIT. Don’t let an agent accidentally pull back thousands of records. Keep your queries tight, including inside subqueries.

When to use Named Query vs Flow vs Apex

My rule of thumb:

Named Query when you just need to read data, especially a record with its related lists. Fast to build, easy to maintain, no code.

Flow when there’s logic involved: decisions, calculations, or you need to create or update records.

Apex when you need complex transformations, callouts, or heavy processing that neither of the above can handle.

Think of Named Query as your clean, safe read layer. It won’t replace Flow or Apex, but it’ll take a big chunk of simple “go fetch this for me” work off their plate.

Wrapping up

Named Query API is one of those features that sounds small until you use it. For admins, it means you can give AI agents and integrations precise, secure, read-only access to exactly the data they need, with nothing more than SOQL and a good description.

Try building one in your dev org this week. Start with something simple like the Account summary above and wire it up to Agentforce or a hosted MCP server. You’ll be surprised how fast it goes.

Got questions or a cool use case? Drop it in the comments. Happy querying!