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 and are read-only from the agent's side.

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 emits a resources/updated notification when its contents change.

The server also emits resources/list_changed when the set of visible resources changes, delivered only to the sessions that can see the change.

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, create_resource, update_resource, delete_resource). An agent works in your personal and team spaces; 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.