Tools API

The Tools API lets you call any MCP tool directly, bypassing the agent loop. This is the same mechanism the MCP App Bridge uses to proxy tool calls from app iframes.

POST /v1/tools/call

Invoke a tool on a specific MCP server. The tool executes immediately and returns the result.

Request body:

Field	Type	Required	Description
server	string	Yes	MCP server name (e.g., weather)
tool	string	Yes	Tool name on that server (e.g., get_forecast)
arguments	object	No	Input arguments for the tool. Defaults to {}.

Note

Use the short tool name (e.g., get_forecast), not the fully qualified name (weather__get_forecast). The server name is provided separately.

Response:

{
  "result": {
    "temp": 62,
    "condition": "partly cloudy",
    "humidity": 78
  },
  "isError": false
}

Field	Type	Description
result	unknown	Tool output. Parsed as JSON if the output is valid JSON, otherwise returned as a string.
isError	boolean	true if the tool reported an error

Error responses:

Status	error	Condition
400	bad_request	Missing server or tool field
404	tool_not_found	Server does not exist, or tool not found on the server

Examples:

curl

curl -X POST http://localhost:27247/v1/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{
    "server": "weather",
    "tool": "get_forecast",
    "arguments": { "city": "San Francisco" }
  }'

Success response

{
  "result": {
    "temp": 62,
    "condition": "partly cloudy",
    "humidity": 78
  },
  "isError": false
}

Error response

{
  "result": "API rate limit exceeded. Try again in 30 seconds.",
  "isError": true
}

System Tools Reference

NimbleBrain includes built-in system tools (prefixed with nb__) for platform management. These are always available and do not require any bundle to be installed.

nb__status

Get platform status information. Use the scope parameter to control what’s returned.

Input	Type	Description
scope	string	"overview" (default), "bundles", "skills", or "config"

nb__search

Unified search across installed tools and the mpak registry.

Input	Type	Description
query	string	Search query
scope	string	"tools" (installed tools) or "registry" (mpak bundles)

nb__set_model_config

Update model selection and runtime limits. Writes atomically to nimblebrain.json. Admin only.

Input	Type	Description
models	object	Role-based model slots: default, fast, reasoning. Each maps to a provider:model-id string.
defaultModel	string	Default model ID (deprecated — use models.default).
maxIterations	number	Max agentic iterations per request (1—25).
maxInputTokens	number	Max input tokens per request.
maxOutputTokens	number	Max output tokens per LLM call.

nb__set_preferences

Set user preferences. Triggered when the user says their name, asks to change timezone/language/theme, or says “call me X”.

Input	Type	Description
displayName	string	User’s display name (e.g., “Matt”).
timezone	string	IANA timezone (e.g., “Pacific/Honolulu”).
locale	string	BCP 47 locale (e.g., “en-US”).
theme	string	Color theme: "system", "light", or "dark".

Returns the updated preferences object on success.

nb__manage_app

Install, uninstall, or configure an app. Gated by the bundleManagement feature flag.

Input	Type	Description
action	string	"install", "uninstall", or "configure"
name	string	Bundle name (e.g., @nimblebraininc/tasks)

nb__manage_skill

Create, edit, or delete user skills. Gated by the skillManagement feature flag.

Input	Type	Description
action	string	"create", "edit", or "delete"
name	string	Skill name

nb__delegate

Spawn a child agent for sub-tasks. Gated by the delegation feature flag. See Multi-Agent Delegation for details.

Input	Type	Description
task	string	Task description for the child agent
tools	string[]	Tool glob patterns the child can access
agent	string	Named agent profile from config (optional)

nb__briefing

Generate a personalized activity briefing for the workspace. Uses the fast model slot. Results are cached per the home.cacheTtlMinutes config value.

Input	Type	Description
force_refresh	boolean	Bypass cache and regenerate. Default: false.

Returns a briefing with greeting, lede, and sections categorized as needs_attention, recent, or coming_up. Used by the Home dashboard on the landing page.

nb__manage_users

Create or delete workspace users. Admin only. Gated by the userManagement feature flag.

nb__manage_workspaces

Workspace CRUD, member management, and conversation sharing. Admin only. Gated by the workspaceManagement feature flag.

Tool Name Resolution

The API constructs the fully qualified tool name by joining the server and tool with a double underscore: {server}__{tool}. For example, server weather and tool get_forecast resolves to weather__get_forecast internally.

MCP App Bridge

The web client uses this endpoint as the backend for the MCP App Bridge. When an app iframe calls a tool via postMessage, the bridge proxies the request to POST /v1/tools/call.

Caution

Tool calls made through this endpoint do not emit data.changed SSE events. This is intentional — iframe-initiated tool calls already know their own results. Emitting data.changed would cause an infinite refresh loop: tool call, then SSE event, then iframe refresh, then another tool call.

The audit log records every tool call made through this endpoint:

[api] tools/call server=weather tool=get_forecast

GET /v1/shell

Returns the shell configuration for the current workspace, including sidebar placements and available endpoints. The web client uses this to render navigation.

Response:

{
  "placements": [...],
  "endpoints": {...}
}

GET /v1/files/:fileId

Serve a previously uploaded file. Returns the file content with the appropriate Content-Type header.

Error responses:

Status	Condition
404	File not found