API reference

ScaiMCP has two surfaces: a regular REST namespace mounted at /v1/modules/scaimcp/ for admin operations, and the MCP transport itself mounted at /mcp. The transport uses JSON-RPC over streamable HTTP and is not browsable as REST. Tools are listed and invoked through the MCP protocol; the REST namespace only exposes catalog introspection.

Authentication#

Both surfaces accept the standard ScaiGrid bearer-token header. Either a JWT (from ScaiKey) or an API key (sgk_...) works:

scdoc

1	`Authorization: Bearer sgk_...`

No MCP-specific token format exists. The token's owning identity (user / service) determines what tools list_tools returns and what call_tool will execute.

REST: `GET /v1/modules/scaimcp/tools`#

Returns the full core tool catalog as JSON, regardless of caller permissions — useful for documentation and admin tooling. Requires scaimcp:access (admin only by default).

bash
curl "$SCAIGRID_HOST/v1/modules/scaimcp/tools" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

Response: array of { name, description, input_schema, required_permission, module_id }. To see what you can call, use the MCP list_tools method instead — that one applies the permission filter.

MCP transport: `POST /mcp`#

The MCP streamable-HTTP transport. Speak JSON-RPC 2.0 framed by the MCP SDK. The relevant methods:

initialize — handshake; clients call this first.
tools/list — returns the caller-filtered tool catalog.
tools/call — invokes one tool by name.

The transport is configured stateless — every request resolves auth and the catalog from scratch. Connection reuse is fine; there is no session state to worry about.

Tool result shape#

Every tool returns a single TextContent block whose text field is a JSON-encoded payload. Successful calls produce the tool's natural result; failures produce:

json
{
  "error": true,
  "code": "TOOL_NOT_FOUND",
  "message": "Unknown tool: foo"
}

Error codes:

Code	Meaning
`TOOL_NOT_FOUND`	Tool name not registered or filtered out by permissions.
`PERMISSION_DENIED`	Caller lacks the tool's `required_permission`.
`MODULE_NOT_ENABLED`	Tool's `module_id` is not enabled for the caller's tenant.
(any `ScaiGridError.code`)	Underlying service error — same code as the REST equivalent would raise.
`RemoteClientError` (or subclass name)	Remote MCP server returned an error or the outbound transport failed.

Core tool catalog#

The following tools are registered at startup. Each one's required_permission is shown so you can predict what your token can see.

Inference#

Tool	Permission	What it does
`inference_chat`	`models:use`	Non-streaming chat completion.
`inference_generate`	`models:use`	Text generation from a single prompt.
`inference_embed`	`models:use`	Generate embeddings for one or more strings.
`inference_image_generate`	`models:use`	Generate one or more images from a text prompt.
`inference_transcribe`	`models:use`	Transcribe base64-encoded audio.
`inference_synthesize`	`models:use`	Synthesise speech; returns base64-encoded audio.

inference_chat accepts model, messages, max_tokens, temperature, top_p, stop, tools, tool_choice, seed. Messages support text and image-URL content parts. Tool calls are returned in the response.

Models#

Tool	Permission	What it does
`models_list`	`models:list`	List frontend models available to your tenant.
`models_get`	`models:list`	Fetch one model's full record.
`models_create`	`models:manage`	Register a new frontend model.
`models_update`	`models:manage`	Replace model fields.
`models_delete`	`models:manage`	Remove a model.

Sessions#

Tool	Permission	What it does
`sessions_create`	`models:use`	Create a new chat session.
`sessions_list`	`models:use`	List your sessions with pagination.
`sessions_get`	`models:use`	Fetch a session with its messages.
`sessions_update`	`models:use`	Update title, metadata, or status.
`sessions_delete`	`models:use`	Soft-delete a session.
`sessions_send_message`	`models:use`	Append message(s) to a session and receive the model response.

Rooms#

Tool	Permission	What it does
`rooms_create`	`models:use`	Create a multi-participant chat room.
`rooms_list`	`models:use`	List rooms in your tenant.
`rooms_get`	`models:use`	Fetch a room with members and recent messages.
`rooms_update`	`models:use`	Update room metadata.
`rooms_delete`	`models:use`	Soft-delete a room.
`rooms_add_member`	`models:use`	Add a user or model member.
`rooms_remove_member`	`models:use`	Remove a member.
`rooms_send_message`	`models:use`	Send a message; model members auto-respond.
`rooms_reply`	`models:use`	Reply to a specific message.

Accounting#

Tool	Permission	What it does
`accounting_list_usage`	`accounting:view_own`	List raw usage records.
`accounting_usage_summary`	`accounting:view_own`	Aggregated summary.
`accounting_export_usage`	`accounting:view_own`	Export up to 1000 records.
`accounting_list_budgets`	`accounting:view_tenant`	List budgets for a scope.
`accounting_create_budget`	`accounting:manage_budgets`	Create a budget.
`accounting_update_budget`	`accounting:manage_budgets`	Update a budget.
`accounting_delete_budget`	`accounting:manage_budgets`	Delete a budget.

IAM#

Tool	Permission	What it does
`me_get`	none (authenticated user)	Get the current user's info, roles, and permissions.
`users_list`	`users:manage`	List users with pagination.
`users_get`	`users:manage`	Fetch one user.
`users_update_roles`	`users:manage`	Set a user's role assignments.
`api_keys_list`	`api_keys:manage`	List your API keys.
`api_keys_create`	`api_keys:manage`	Create an API key.
`api_keys_revoke`	`api_keys:manage`	Revoke an API key.
`role_mappings_list`	`users:manage`	List ScaiKey group-to-role mappings.
`role_mappings_create`	`users:manage`	Create a group-to-role mapping.
`role_mappings_update`	`users:manage`	Update a mapping.
`role_mappings_delete`	`users:manage`	Delete a mapping.

Webhooks#

Tool	Permission	What it does
`webhooks_list`	`webhooks:manage`	List outbound webhooks.
`webhooks_create`	`webhooks:manage`	Create a webhook.
`webhooks_update`	`webhooks:manage`	Update a webhook.
`webhooks_delete`	`webhooks:manage`	Delete a webhook.
`webhooks_test`	`webhooks:manage`	Send a test event.
`webhooks_list_deliveries`	`webhooks:manage`	List delivery attempts.

Modules#

Tool	Permission	What it does
`modules_list`	none (authenticated user)	List all registered modules.
`modules_get`	none (authenticated user)	Get details of one module.
`modules_get_config`	none (authenticated user)	Get resolved config for a module.
`modules_enable`	`modules:manage`	Enable a module for a scope.
`modules_disable`	`modules:manage`	Disable a module for a scope.
`modules_update_config`	`modules:manage`	Update global config.

Platform admin#

These cover partners, tenants, backends, routing, model access, audit, ScaiKey sync, templates, and nodes. All require admin:access (or routing:manage for the routing family).

Tool	Permission
`partners_list`, `partners_get`, `partners_update`	`admin:access`
`tenants_list`, `tenants_create`, `tenants_get`, `tenants_update`	`admin:access`
`backends_list`, `backends_create`, `backends_get`, `backends_update`, `backends_delete`, `backends_health`	`admin:access`
`routing_policies_list`, `routing_policies_create`, `routing_policies_get`, `routing_policies_update`, `routing_policies_delete`	`routing:manage`
`routing_mappings_list`, `routing_mappings_create`, `routing_mappings_update`, `routing_mappings_delete`	`routing:manage`
`model_access_list`, `model_access_create`, `model_access_update`, `model_access_delete`	`routing:manage`
`audit_list`	`admin:access`
`sync_full`, `sync_tenant`, `sync_status`	`admin:access`
`templates_list`, `templates_create`, `templates_get`, `templates_update`, `templates_delete`, `templates_apply`	`admin:access`
`nodes_list`	`admin:access`

Module-contributed tools#

Modules add their own tools via get_mcp_tools(). They are filtered by module-enabled status and by their own required_permission. Check each module's documentation for the exact name and schema:

ScaiBunker — bunker lifecycle, exec, file I/O.
ScaiMatrix — collection search and ingestion.
ScaiQueue — publish, claim, complete.
ScaiBot — bot management as MCP tools (when enabled).

A module's tools appear in list_tools only when the module is enabled for the caller's tenant.

Cloud MCP aggregation#

When ScaiLink is loaded, ScaiMCP additionally lists tools from cloud MCP servers users have registered through ScaiLink's cloud registry. These tools have a four-segment name:

gdscript
remote.{user_id|tenant}.{slug}.{tool}

Personal registrations show only to the registering user.
Tenant registrations show to every user with scailink:remote.use.

Calls to any name beginning with remote. are dispatched through ScaiLink's outbound MCP client — descriptions, input schemas, and behaviour come from the upstream server. Errors are surfaced under the upstream error class name with a human-readable message.

See Tool naming for the full convention.

Rate limits#

MCP tool invocations count against the same rate limits as REST calls to the underlying endpoint. There is no separate MCP quota; one MCP inference_chat call costs exactly what one POST /v1/inference/chat costs against your tenant budget.

Audit#

Every tool call is logged through the standard ScaiGrid audit pipeline. Filter by module=scaimcp or by the underlying action (inference.chat, models.create, etc.) — there is no MCP-specific audit category because MCP is just another entry point into the same services.