---
summary: "Every ScaiMCP endpoint and built-in tool \u2014 transport mount, admin routes,\
  \ and the full core tool catalog grouped by domain."
title: API reference
path: reference/api
status: published
---

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:

```
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:

```
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](../concepts/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.