Skip to content
Back to blog

MCP tool permissions: show each user only the tools they can use

How to add role-based access control to an MCP server: hide tools, prompts, and resources a caller is not allowed to use, and reject direct calls, with one authorize policy in xmcp.

To give different users different MCP tools, check the caller's verified identity in two places: when the server lists its tools, and when a tool is called. In xmcp both checks are one function. Export authorize from src/middleware.ts, return false for a component the caller may not use, and xmcp hides it from every listing and rejects direct access as if it did not exist.

This guide follows the repository's authorization policy example.

What is the difference between authentication and authorization in MCP?

Authentication answers who is calling. Authorization answers what that caller may do.

AuthenticationAuthorization
QuestionWho is this?May they use this tool?
DecidedOnce per request, before MCP handlingPer component, per operation
In xmcpAn auth plugin or HTTP middleware supplies authInfoThe authorize export reads authInfo and decides
Failure looks likeHTTP 401The component is absent or "not found"

Authentication has to come first. See How to Add Authentication to Your MCP Server for OAuth and the provider plugins. This guide starts where a request already has a verified caller.

Why is hiding a tool from the list not enough?

Because a client can call a tool by name without listing it first. Filtering tools/list changes what the model sees. It does not stop a request for tools/call with the hidden tool's name.

A complete policy covers every way to reach a component:

  • Listings: tools/list, prompts/list, resources/list, resources/templates/list, and skill catalogs.
  • Direct access: tools/call, prompts/get, resources/read.
  • Completions for prompt and resource template arguments.

Writing those checks by hand means keeping several filters in sync. The authorize export applies one decision to all of them.

How do I write the policy?

Decide how a component declares what it requires. The example uses tags: a tool tagged admin requires the admin role.

src/tools/refund-invoice.ts

The policy compares those tags with the scopes on the caller's authInfo:

src/middleware.ts

The default export is ordinary HTTP middleware. It stands in for your authentication provider: it checks a key and attaches verified authInfo to the request. The two keys are public demonstration values.

The authorize export is the policy. It receives the request context, the component being accessed, and the operation (list, call, get, read, or complete). Only an explicit true allows access. A component with no tags requires nothing, so every authenticated caller can use it. A caller with no authInfo fails every role check.

No tool wraps itself in a permission check. Tools declare what they need in metadata, and the policy lives in one file.

What does each caller see?

ComponentTagsSupport callerAdmin caller
get-statusnoneListedListed
list-invoicessupportListedListed
refund-invoiceadminHiddenListed
reports://revenueadminHiddenListed

When the support caller calls the hidden tool by name, the response is the same error an unknown tool produces:

JSON

Matching the unknown-tool error is deliberate. A caller cannot use the response to learn which restricted tools exist. Reading reports://revenue as the support caller returns Resource not found in the same way.

Run the example

Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:

Shell

List the tools as the support caller:

Shell

The listing has get-status and list-invoices. Change the key to demo-admin and refund-invoice appears. The example's README has the direct call and the resource read.

Common questions

Can different users see different tools on the same MCP server?

Yes. The server decides per request. In xmcp, an authorize policy reads the caller's verified authInfo and returns whether each component is available, so two callers of the same endpoint get different listings.

Does the policy run on every request?

Yes. HTTP is stateless, so each request is authenticated and authorized on its own. An earlier request does not establish an identity for later ones.

Can the policy look at the tool's arguments?

Yes. On a tool call, ctx.params.arguments holds the raw arguments, before validation, defaults, or coercion. Check ctx.method first and type-check the values yourself. This lets a policy allow a tool in general and deny it for a specific record.

Does it apply to prompts, resources, and skills?

Yes. The same function covers tools, prompts, resources, resource templates, and skill catalogs. For skills, protect the skill://<name>/ prefix to restrict every file. See How to serve Agent Skills.

Should listings be cached when they vary per caller?

Keep their cache scope private, which is the default. A public cache hint tells clients the result is the same for every caller. See Caching MCP listings.

Where does authInfo come from?

From your authentication integration, for the current request only. With HTTP middleware, verify the caller and set req.auth yourself, as the example does. authInfo is never inferred from headers: the built-in API-key helper only validates the key, and the JWT helper populates req.user.

Next steps

One framework to rule them all