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).
A tool that works on any connection
Section titled “A tool that works on any connection”Accept a URI, accept inline content as the fallback, and let the capability decide which is used.
"""A tool that reads a workspace file through the host, and takes the text inline elsewhere."""
from fastmcp import Context, FastMCPfrom fastmcp.tools import ToolResultfrom mcp.types import TextResourceContents
from nimblebrain_server_sdk import READS, hostfrom 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
availablebefore reading. It is true when the host advertised the capability withreadenabled 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
ValueErrorhere would reach the agent as an unclassified failure. - Say in the tool’s description which argument to use when. The model picks the argument.
The API
Section titled “The API”from nimblebrain_server_sdk import host
files = host(ctx)
files.available # read is enabled, and the connection can carry itfiles.list_available # the same for listfiles.supports_scheme("files") # the URI scheme is on the host's allowlist
result = await files.read("files://fl_abc123") # an MCP ReadResourceResultlisting = await files.list(mime_type="text/csv") # an MCP ListResourcesResultfor 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.
Errors
Section titled “Errors”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 |
Test it
Section titled “Test it”The in-memory client advertises no host-resources capability, so a test exercises the fallback on both eras.
"""The tool on a connection with no host-resources: inline text works, a URI is refused."""
import pytestfrom fastmcp import Clientfrom 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`.", } }Related
Section titled “Related”- Host resources extension: the capability, the methods, and which files a server can see
- Errors
- API reference