Tools

Tools are the actions an MCP client invokes on your behalf. The client sends a JSON-RPC tools/call with the tool name and an arguments object. Each tool below lists those arguments and shows an example. Every tool except create_organization needs an OAuth connection or an API key with the right access level for the libraries it touches. set_asset_approval accepts only an OAuth connection. Each tool returns the same payload shape as the matching REST endpoint.

Tool	Access	Purpose
`whoami`	Read	Resolve the organizations and libraries your credential can act on.
`create_organization`	Anonymous	Create an organization, library, and API key for an agent, with no account needed.
`create_library`	Write	Create a library in an existing organization.
`rename_library`	Write	Rename a library.
`list_libraries`	Read	List libraries in an organization.
`list_assets`	Read	List assets in a library (paginated, tag filter).
`get_asset`	Read	Get one asset by id.
`search_assets`	Read	Search assets across libraries (ranked, highlights).
`list_tags`	Read	List a library's tags, by usage count.
`upload_asset`	Write	Upload one file from a URL or inline base64.
`upload_assets`	Write	Upload up to 20 files in one call.
`delete_assets`	Write	Move up to 100 assets to trash (soft delete).
`tag_assets`	Write	Apply up to 20 tags to up to 100 assets.
`untag_assets`	Write	Remove up to 20 tags from up to 100 assets.
`update_asset_description`	Write	Replace one asset's description (verbatim).
`set_asset_approval`	Read	Set one asset's approval state (OAuth connections only).
`transfer_assets`	Write	Move up to 100 assets between libraries.
`promote_variant`	Write	Make a variant the asset's default, at the asset's existing URL.

`whoami`

Resolves the organizations and libraries your credential (an API key or an OAuth connection) can act on. It takes no arguments and reads your Bearer credential. Call it first when the credential is all you have: it returns the organizationId that every other tool takes as input, along with the authorized library ids and the plan.

Parameters

None.

Returns

{ organizationId, organizationName, plan, libraries } for an API key or a connection bound to one organization. A connection granted all your organizations returns { organizations: [...] } instead, with one such entry per organization you belong to. libraries has one { library, access } entry per library your credential can act on, where access is "write" (read and write) or "read" (read-only). organizationName and plan are null when none is set. Use list_libraries for the libraries' names and counts.

An OAuth connection adds user: { name }, the account the connection acts as, which a client can use to label the connection. An API key carries no user, since a key belongs to an organization rather than a person.

Example

{}

`create_organization`

Creates a new organization with a starter library, so an AI agent can upload files on someone's behalf. It needs no Raster account or API key. Pass the person's email and the tool returns an API key for the upload, list, and search tools, plus a link the person opens to claim the organization into their Raster account. The library and everything in it is held for 30 days for the person to claim. Once claimed, it is a permanent part of their account. If you already have an organization and key and need another library, use create_library.

Parameters

Prop

Type

Returns

What the agent needs to start uploading:

organizationId and libraryId: the target for upload_asset and the other tools. Pass both on every call.
apiKey: the key those calls authenticate with. It is returned once, so save it.
claimUrl: the link the user opens to claim the library into their Raster account.
expiresAt: when the 30-day claim window closes.
emailSent: true if the claim link was emailed. If false, show the user the claimUrl directly so they can still claim it.

Example

{ "email": "<your-email>", "name": "Sample library" }

The tool result carries this payload under data:

{
  "organizationId": "k3m9x7p2qar8zt",
  "libraryId": "b7n2w4j8x1c5dq",
  "emailSent": true,
  "apiKey": "pk_…",
  "claimUrl": "https://raster.app/claim/…",
  "expiresAt": "2026-06-27T00:00:00.000Z"
}

The agent then calls upload_asset and the other tools with the returned apiKey as the Bearer token and the returned organizationId and libraryId as the target.

Call this from the no-account endpoint https://mcp.raster.app/anonymous, which needs no credential. See Authentication.

`create_library`

Creates a library in an organization you already have access to. Your whole team sees it in the Raster app. With an API key, the key needs Write access, and the library is granted to the key so you can upload to it right away. A read-only key cannot create libraries. Over an OAuth connection, your account must be an organization Owner, or the call fails with FORBIDDEN (403). To create a library with no account or key, use create_organization.

Parameters

Prop

Type

Returns

The new Library, with zeroed counters and no tags. Fails when the credential is invalid, the slug is taken, a free-plan library cap is reached, or an API key is read-only (API_KEY_READ_ONLY, 403).

Example

{ "organizationId": "acme-co", "name": "Marketing", "slug": "marketing" }

`rename_library`

Renames a library your credential has access to. The new name shows everywhere the library appears, including each team member's view. The URL slug stays the same.

Parameters

Prop

Type

Returns

The updated Library. Fails with 404 when your credential cannot reach the library or the library does not exist.

Example

{ "organizationId": "acme-co", "libraryId": "marketing", "name": "Marketing 2026" }

`list_libraries`

Lists the libraries in an organization that your credential can reach.

Parameters

Prop

Type

Returns

An array of Library objects.

Example

{
  "organizationId": "acme-co"
}

Pagination for list_libraries is zero-based (page 0 is the first page), while list_assets and search_assets are 1-based (page 1 is the first page). This matches the REST API.

`list_assets`

Lists assets in a library, paginated and optionally filtered by tag.

Parameters

Prop

Type

Returns

An array of Asset objects.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "page": 1,
  "pageSize": 20,
  "tags": ["landscape", "nature"]
}

`get_asset`

Fetches a single asset by id. It returns the same Asset payload that list_assets returns for each asset. Use it to read one asset's url, tags, description, and dimensions without paging the list.

Parameters

Prop

Type

Returns

The Asset. Fails with a 404 when your credential cannot reach the library, or the asset does not exist, belongs to another library, or is trashed.

Example

{ "organizationId": "acme-co", "libraryId": "marketing", "assetId": "k3m9x7p2qar8zt" }

`search_assets`

Searches assets across the libraries your credential authorizes and returns hits ranked by relevance, with optional highlighted snippets. The search is scoped to the organization: omit libraries to search every authorized library, or pass a subset.

Parameters

Prop

Type

Returns

A SearchResult: { hits, found, page }, where each SearchHit is an Asset plus optional highlights (matched snippets, with <mark> tags on the name field) and a relevance score.

Example

{
  "organizationId": "acme-co",
  "q": "sunset",
  "libraries": ["barcelona", "lisbon"],
  "page": 1,
  "pageSize": 10
}

Naming an unauthorized library fails the whole call with API_KEY_NOT_AUTHORIZED_FOR_LIBRARY. Omit libraries to search every library your credential authorizes.

Lists the tags used in a library, sorted by usage count (descending).

Parameters

Prop

Type

Returns

An array of Tag objects.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "limit": 10
}

The `Source` shape

upload_asset and upload_assets take their file payloads as a Source, a tagged union on kind. A source is either a remote URL the server fetches or an inline base64 payload:

// kind: "url" — the server fetches the file.
{ "kind": "url", "url": "https://example.com/cat.jpg" }

// kind: "base64" — you supply the bytes inline.
{
  "kind": "base64",
  "filename": "screenshot.png",
  "mimeType": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAA..."
}

The url variant must be an http(s) URL. Other schemes are rejected, and so are URLs that resolve to private or internal network addresses. A URL the server can't fetch (its host doesn't resolve or can't be reached, or the fetch times out) fails with BAD_USER_INPUT (400) and the message Upload source URL could not be fetched. A URL file is held to the per-file size cap (1 GB): the server stops the download once the file passes the cap and refuses the file. The base64 variant requires filename and mimeType and carries up to 24 MB decoded, because the request body is capped at 32 MB. A request over that cap is refused with PAYLOAD_TOO_LARGE (413) and nothing is uploaded. Send a larger file by URL.

`upload_asset`

Uploads a single file to a library.

Parameters

Prop

Type

Returns

The same UploadedAssets shape as the REST upload endpoint. assets is a one-element array of Asset, each with a permanent CDN url (the canonical reference for the image) and an id for other API calls. When parentId is set, the returned asset carries that parentId and an appUrl that opens the parent asset with the variant selected. The variant is nested under the parent's variants.

Upload is asynchronous. The response returns immediately with the asset's url and id, and the url serves right away. The asset appears in list_assets and search_assets a few seconds later. Keep the url: it is permanent.

Example

Fetch from a URL:

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "source": { "kind": "url", "url": "https://example.com/cat.jpg" }
}

Upload bytes you generated locally (e.g. a screenshot):

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "source": {
    "kind": "base64",
    "filename": "screenshot.png",
    "mimeType": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

To attach the file as a variant of an existing asset, pass parentId:

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "parentId": "<PARENT_ASSET_ID>",
  "source": { "kind": "url", "url": "https://example.com/variant.jpg" }
}

`upload_assets`

Uploads between 1 and 20 files in a single call. Sources may mix url and base64.

Parameters

Prop

Type

Returns

UploadedAssets with one Asset per uploaded file, each with a permanent CDN url and an id, plus a responseText summary. On full success assets[i] corresponds to sources[i].

As with upload_asset, upload is asynchronous. Each url is returned immediately and serves as soon as the call returns. The assets appear in list_assets and search_assets a few seconds later.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "sources": [
    { "kind": "url", "url": "https://example.com/a.jpg" },
    { "kind": "url", "url": "https://example.com/b.jpg" }
  ]
}

Every source is validated (schema, address safety) before any byte is stored. If any source fails these checks, or the request body passes 32 MB, the whole call fails and nothing is uploaded. A URL that cannot be fetched (an error status or a failed connection) also fails the whole call before anything is stored. A file is left out when it is refused for its type, when it cannot be opened, or when it is a URL file over the 1 GB per-file size cap: the other files upload, and responseText names the refused file. If every file is refused this way, the call fails with BAD_USER_INPUT.

`delete_assets`

Moves between 1 and 100 assets by id to trash (soft delete, like the Raster app). They leave list and search results right away, stay recoverable from trash, and are permanently removed after 30 days.

Trashing an asset also trashes its variants. A variant cannot be trashed on its own: pass the original's id. A variant id fails the whole call with BAD_USER_INPUT (400).

Parameters

Prop

Type

Returns

{ success, message, ids }, the same DeletedAssets payload as the REST delete endpoint. ids lists the assets actually moved to trash. The call is idempotent: re-deleting already-trashed ids returns "Moved 0 assets to trash", ids: [], and success: true. Full semantics: DELETE /assets.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "ids": ["asset-123", "asset-456"]
}

`tag_assets`

Applies between 1 and 20 tags to between 1 and 100 assets in a single library, in one call.

Parameters

Prop

Type

Returns

{ taggedCount }, the number of (asset, tag) pairs this call added. Pairs the asset already carries are skipped.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetIds": ["asset-123", "asset-456"],
  "tags": ["sunset", "landscape"]
}

`untag_assets`

Removes between 1 and 20 tags from between 1 and 100 assets. It takes the same arguments as tag_assets.

Parameters

Prop

Type

Returns

{ untaggedCount }, the number of (asset, tag) pairs this call removed. Pairs the asset didn't carry are skipped.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetIds": ["asset-123", "asset-456"],
  "tags": ["draft"]
}

`update_asset_description`

Replaces the description on a single asset, written verbatim.

Parameters

Prop

Type

Returns

{ assetId, description }, echoing the stored description so the caller can confirm it without an extra read.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetId": "asset-123",
  "description": "Golden hour over the Mediterranean."
}

`set_asset_approval`

Sets the approval of a single asset (an original or a variant), with an optional note. Each call replaces the asset's previous approval, including its note. The asset's uploader gets an email when it is set to approved or needs_changes, unless they set it themselves.

This tool runs only over an OAuth connection, whose account needs access to the library at any role, Viewer included. An API key can read an asset's approval but cannot set it: the call fails with APPROVAL_REQUIRES_USER (403). The organization needs a paid plan: without one the call fails with PAID_PLAN_REQUIRED (403).

Parameters

Prop

Type

Returns

{ assetId, approval }: the asset id and the Approval that was written, so the caller can confirm without an extra read.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetId": "asset-123",
  "state": "needs_changes",
  "note": "Crop tighter on the left."
}

A state the organization does not use, or an asset that is not in the library, fails with BAD_USER_INPUT. A value other than in_review, approved, or needs_changes is refused before the tool runs with an invalid-arguments error.

`transfer_assets`

Moves between 1 and 100 assets from one library to another in the same organization. An asset's variants move with it. A variant cannot be transferred on its own: pass the original's id. A variant id fails the whole call with BAD_USER_INPUT (400).

Parameters

Prop

Type

Returns

{ transferredCount, sourceLibraryId, targetLibraryId }. Both library ids are echoed so the caller can confirm the move without another call.

Example

{
  "organizationId": "acme-co",
  "sourceLibraryId": "barcelona",
  "targetLibraryId": "archive",
  "assetIds": ["asset-123", "asset-456"]
}

A target library in another organization fails with API_KEY_NOT_AUTHORIZED_FOR_LIBRARY (404), the same response as a library your credential cannot reach.

`promote_variant`

Makes one of an asset's variants its default. The variant's image replaces what the asset serves at the same URL, so anything already embedding that URL shows the new image without being updated. A published asset can be corrected or replaced without changing any link to it.

The previous default is kept as a new variant with the name it had, so it can be promoted back. The asset keeps its id and URL and takes the promoted variant's name. Its description and the tags generated from its image follow the image: the promoted variant hands over any it carries, and the preserved variant keeps the ones that described it. Tags you added yourself stay on the asset. The promoted variant's own entry is removed, since its image is now the asset's.

Parameters

Prop

Type

Returns

{ assetId, promotedVariantId, demotedVariantId }, so the caller can update local state from one response. demotedVariantId is the new variant holding the previous default's image.

The result confirms the promote is accepted. The image swap and the removal of the promoted variant's entry complete a moment later. Re-fetch the asset after a short delay to see the change. Its variants list is final once the swap finishes.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "variantId": "var789"
}

This tool is marked destructive: it replaces the file behind a URL that may already be published. Confirm with the user before calling it.

Rejected with BAD_USER_INPUT when the id names an original rather than a variant, when the variant is archived or still processing, when the asset is not live, when the asset is itself still being processed (a video whose poster is not ready yet), when the asset is neither an image nor a video, or when the variant is a different kind of media than the asset. If a promote is already running on the same asset, the call fails with CONFLICT. Wait and retry.

Limits

Tool	Cap
`list_assets`	At most 50 tags in the `tags` filter.
`search_assets`	`pageSize` clamps to 50 (default 10).
`upload_asset` / `upload_assets`	1 GB per file; 24 MB decoded per inline `base64` source (the request body, every inline source included, is capped at 32 MB); up to 20 files per `upload_assets` call.
`delete_assets`	Up to 100 ids per call.
`tag_assets` / `untag_assets`	Up to 100 asset ids and 20 tag names per call.
`update_asset_description`	Up to 2000 characters.
`set_asset_approval`	`note` up to 500 characters.
`transfer_assets`	Up to 100 asset ids per call.

Exceeding a count or length cap fails the call with an invalid-arguments error before changing anything. A request body over 32 MB fails with PAYLOAD_TOO_LARGE (413), and nothing is uploaded. A URL file over the 1 GB per-file cap is refused: upload_assets leaves it out and names it in responseText, and upload_asset fails with BAD_USER_INPUT (400), or with PAYLOAD_TOO_LARGE (413) when parentId is set.

On this page