Skip to main content

Resources

A resource is a piece of content — a document, file, or data blob — that your agent can read over MCP. Resources are addressed by URI. The native MCP resource surface is read-only; governed management tools separately let an authorized agent create, update, patch, and delete them.

How an MCP client consumes resources​

apistash advertises the resources capability with subscriptions, so a connected client can:

  • resources/list — discover the resources available to the current credential.
  • resources/read — fetch a resource's contents by URI.
  • resources/subscribe / resources/unsubscribe — watch a resource; the server sends a best-effort resources/updated notification when its contents change.

The server also sends a best-effort resources/list_changed notification when a session's visible list may have changed. Notifications can be missed during a disconnect or replica delivery gap, so clients that require a fresh catalog must call resources/list independently, for example after reconnecting. A removal can notify a conservative set of sessions because the deleted resource's exact former audience is no longer available. The notification contains no resource data; every resources/list result remains permission-filtered.

Errors​

The native resource methods have no tool-result error channel, so a failure surfaces as a JSON-RPC protocol error. Anything your client can act on — for example a credential without the resources capability — is an invalid_params error carrying a precise, stable code in its data, so you can branch on the code instead of parsing the message. A resource outside your visible set fails as method_not_found, indistinguishable from one that doesn't exist.

The resource management tools are ordinary tools and follow the tool error model instead, returning failures as isError tool results.

Enabled flag​

Each resource carries an enabled flag. Only enabled resources are advertised on MCP — disabling a resource hides it from resources/list and resources/read without deleting it.

Names, URIs, and ownership​

Every resource has a URI (its address) and a human-readable name. Like prompts, resources belong to an owner — you, a team, or an organization — and visibility is computed per credential.

For personal API keys you can further restrict which resource URIs a key may reach — see Authentication.

Where resources come from​

You can create and manage resources three ways: in the dashboard, through the REST API, or by letting an agent do it over MCP with the management tools (list_resources, get_resource, grep_resource, create_resource, update_resource, patch_resource, and delete_resource). With a credential that represents a user, an agent can work in that user's personal space; team-space work requires a bound team and the matching permission. Publishing to the organization catalogue stays a deliberate dashboard action.

What a credential can see is governed by the access model.

info

Resources are visible only to a credential that carries the resources capability and is allowed to reach them by the access model.