Skip to content

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.

Python 3.13 or later.

Terminal window
uv init notes && cd notes
uv add nimblebrain-server-sdk

pip install nimblebrain-server-sdk works too.

notes.py
"""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 code
add_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, ADDS or CHANGES. Under the MCP specification’s defaults an unannotated tool is a destructive write. See Tools and annotations.
  • save_note announces its write so open views re-read. See Announcing changes.
  • A failure is a ServiceError with a code from a closed set. add_error_contract returns it to the caller in the shape the host reads. See Errors.
  • The resource marked with facet_meta is a count the host shows beside the server’s name. See Facets.
Terminal window
uv run python notes.py

The server listens at http://127.0.0.1:8000/mcp. Any MCP client can connect to it.

test_notes.py
"""The notes server, checked the way a host reads it, on both protocol eras."""
import pytest
from fastmcp import Client
from 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-25
async 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."}
}
Terminal window
uv add --dev pytest pytest-asyncio
uv run pytest

Set 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.

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:

<workDir>/workspaces/<wsId>/workspace.json
{
"connectors": [
{ "url": "http://127.0.0.1:8000/mcp", "serverName": "notes" }
]
}
<workDir>/nimblebrain.json
{ "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.