Server SDK quickstart
nimblebrain-server-sdk is the Python package for building an MCP server that runs on NimbleBrain. It gives a FastMCP server what NimbleBrain’s host expects of it: annotated tools, change announcements, the ai.nimblebrain extensions, skills, and one error contract. The MCP protocol itself comes from FastMCP and the mcp package.
This page builds a connector: a server with tools and no interface. To add an interface, see Build for NimbleBrain.
1. Install
Section titled “1. Install”Python 3.13 or later.
uv init notes && cd notesuv add nimblebrain-server-sdkpip install nimblebrain-server-sdk works too.
2. Write the server
Section titled “2. Write the server”"""A complete connector: two tools, a count the host shows, and the error contract."""
from fastmcp import Context, FastMCP
from nimblebrain_server_sdk import ( ADDS, FACETS_EXTENSION_ID, READS, add_error_contract, add_platform_extension, announce_resource_list_changed, facet_count, facet_meta, new_prefixed_id,)from nimblebrain_server_sdk.errors import ErrorCode, ServiceError
mcp = FastMCP("notes")add_error_contract(mcp) # a ServiceError a tool raises reaches the caller with its codeadd_platform_extension(mcp, FACETS_EXTENSION_ID)
NOTES: dict[str, str] = {}
@mcp.tool(annotations=ADDS)async def save_note(text: str, ctx: Context) -> dict[str, str]: """Save a note and return its id.""" if not text.strip(): raise ServiceError(ErrorCode.BAD_INPUT, "`text` is empty.") note_id = new_prefixed_id("nt") NOTES[note_id] = text await announce_resource_list_changed(ctx) # after the write, so open views re-read return {"id": note_id}
@mcp.tool(annotations=READS)async def get_note(note_id: str) -> dict[str, str]: """Read one note by id.""" if note_id not in NOTES: raise ServiceError(ErrorCode.NOT_FOUND, "No note has that id.") return {"id": note_id, "text": NOTES[note_id]}
@mcp.resource( "notes://facets/total", name="notes-total", title="Notes", mime_type="application/json", meta=facet_meta("info"),)async def notes_total() -> str: return facet_count(len(NOTES))
if __name__ == "__main__": mcp.run(transport="http", host="127.0.0.1", port=8000)- Every tool carries
READS,ADDSorCHANGES. Under the MCP specification’s defaults an unannotated tool is a destructive write. See Tools and annotations. save_noteannounces its write so open views re-read. See Announcing changes.- A failure is a
ServiceErrorwith a code from a closed set.add_error_contractreturns it to the caller in the shape the host reads. See Errors. - The resource marked with
facet_metais a count the host shows beside the server’s name. See Facets.
3. Run it
Section titled “3. Run it”uv run python notes.pyThe server listens at http://127.0.0.1:8000/mcp. Any MCP client can connect to it.
4. Test it
Section titled “4. Test it”"""The notes server, checked the way a host reads it, on both protocol eras."""
import pytestfrom fastmcp import Clientfrom notes import NOTES, mcp
from nimblebrain_server_sdk.testing import Mode, served_facets
@pytest.fixture(autouse=True)def empty_store() -> None: NOTES.clear()
@pytest.mark.parametrize("mode", ["auto", "legacy"]) # 2026-07-28, then 2025-11-25async def test_a_saved_note_reads_back_and_is_counted(mode: Mode) -> None: async with Client(mcp, mode=mode) as client: saved = await client.call_tool("save_note", {"text": "hello"}) note = await client.call_tool("get_note", {"note_id": saved.data["id"]}) assert note.data == {"id": saved.data["id"], "text": "hello"} assert await served_facets(mcp, mode) == { "notes-total": {"title": "Notes", "level": "info", "count": 1} }
async def test_a_missing_note_is_a_not_found_error() -> None: async with Client(mcp) as client: result = await client.call_tool("get_note", {"note_id": "nt_0"}, raise_on_error=False) assert result.is_error assert result.structured_content == { "error": {"code": "not_found", "retryable": False, "message": "No note has that id."} }uv add --dev pytest pytest-asynciouv run pytestSet asyncio_mode = "auto" under [tool.pytest.ini_options] in pyproject.toml, so async def tests run.
fastmcp.Client(mcp, mode=...) chooses the protocol era: "auto" negotiates 2026-07-28 and "legacy" runs the 2025-11-25 initialize handshake. A host may connect on either, so test both. See Testing.
5. Connect it to NimbleBrain
Section titled “5. Connect it to NimbleBrain”NimbleBrain connects to a server by URL and never starts one. With the server running, point a development workspace at it and allow the loopback address:
{ "connectors": [ { "url": "http://127.0.0.1:8000/mcp", "serverName": "notes" } ]}{ "allowInsecureRemotes": true }Start NimbleBrain (bun run dev in the platform repository) and ask the agent to save a note.
- Give the agent instructions for your tools: Skills.
- Keep data per tenant and workspace in Postgres: Data.
- Serve metrics, logs and traces: Observability.
- Start from a repository with CI, packaging and a manifest already set up: the Python server template.
- Every public name: the API reference.