Skip to content

Host resources

With ai.nimblebrain/host-resources, a tool takes a URI such as files://fl_abc123 and the server reads the file from the host. The model passes a short reference and never copies the bytes. The protocol is the host resources extension. The SDK wraps the capability check, the method names and the result types: you write await host(ctx).read(uri).

Accept a URI, accept inline content as the fallback, and let the capability decide which is used.

host_files.py
"""A tool that reads a workspace file through the host, and takes the text inline elsewhere."""
from fastmcp import Context, FastMCP
from fastmcp.tools import ToolResult
from mcp.types import TextResourceContents
from nimblebrain_server_sdk import READS, host
from nimblebrain_server_sdk.errors import ErrorCode, ServiceError, to_tool_error
mcp = FastMCP("summaries")
@mcp.tool(annotations=READS)
async def word_count(
ctx: Context, file_uri: str | None = None, text: str | None = None
) -> dict[str, int] | ToolResult:
"""Count the words in a document. Pass `file_uri` for a workspace file, or `text` inline."""
files = host(ctx)
if file_uri and files.available:
content = (await files.read(file_uri)).contents[0]
if not isinstance(content, TextResourceContents):
return to_tool_error(
ServiceError(ErrorCode.BAD_INPUT, "That file is not text. Pass a text file.")
)
text = content.text
elif file_uri:
# No host-resources on this connection (the host does not offer it, or the connection
# negotiated 2026-07-28): tell the agent how to call again, as an error it can read.
return to_tool_error(
ServiceError(
ErrorCode.BAD_INPUT,
"This connection cannot read workspace files. Pass the contents as `text`.",
)
)
if text is None:
return to_tool_error(ServiceError(ErrorCode.BAD_INPUT, "Pass `file_uri` or `text`."))
return {"words": len(text.split())}
  • Check available before reading. It is true when the host advertised the capability with read enabled and the connection can carry the request.
  • Narrow the content’s type. A text MIME type comes back as TextResourceContents; anything else as a base64 blob.
  • Return the fallback as a tool error the agent can act on. The message names the argument to use instead. Raising ValueError here would reach the agent as an unclassified failure.
  • Say in the tool’s description which argument to use when. The model picks the argument.
from nimblebrain_server_sdk import host
files = host(ctx)
files.available # read is enabled, and the connection can carry it
files.list_available # the same for list
files.supports_scheme("files") # the URI scheme is on the host's allowlist
result = await files.read("files://fl_abc123") # an MCP ReadResourceResult
listing = await files.list(mime_type="text/csv") # an MCP ListResourcesResult
for entry in listing.resources:
print(entry.name, entry.uri)

list takes mime_type and tags filters. The whole list comes back in one response; pagination is not supported.

read and list raise HostCapabilityMissing when the connection cannot carry the request. Its message says whether the host did not advertise the capability or the connection negotiated 2026-07-28, and protocol_version carries the version in the second case.

An error the host returns arrives as mcp.shared.exceptions.MCPError. Match on .code:

Code Constant Meaning
-32002 RESOURCE_NOT_FOUND Resource not found, or not visible to this caller
-32004 RATE_LIMITED Rate limited; error.data carries retryAfterMs
-32005 RESPONSE_TOO_LARGE The resource exceeds the host’s size limit; error.data carries size and maxSize
-32602 INVALID_PARAMS Unsupported URI scheme, malformed tags, or a pagination cursor

The in-memory client advertises no host-resources capability, so a test exercises the fallback on both eras.

test_host_files.py
"""The tool on a connection with no host-resources: inline text works, a URI is refused."""
import pytest
from fastmcp import Client
from host_files import mcp
from nimblebrain_server_sdk.testing import Mode
@pytest.mark.parametrize("mode", ["auto", "legacy"])
async def test_inline_text_is_counted_and_a_uri_asks_for_text(mode: Mode) -> None:
async with Client(mcp, mode=mode) as client:
counted = await client.call_tool("word_count", {"text": "three short words"})
assert counted.structured_content == {"words": 3}
refused = await client.call_tool(
"word_count", {"file_uri": "files://fl_1"}, raise_on_error=False
)
assert refused.is_error
assert refused.structured_content == {
"error": {
"code": "bad_input",
"retryable": False,
"message": "This connection cannot read workspace files. Pass the contents as `text`.",
}
}