Prisme.ai Storage - Prisme.ai

The Prisme.ai Storage app is a client connector to the Prisme.ai Storage backend (the slug:storage workspace running in the current environment). It can be consumed two ways: as a remote MCP server that Agent Factory agents call as tools, or as a Builder app whose instructions you call directly from DSUL automations. It exposes the full Storage REST API — files, vector stores, vector-store files, web crawling, RBAC access bindings, per-store API keys, agent skills and admin diagnostics — grouped into 8 entity tools covering ~38 operations. Unlike third-party SaaS connectors, this connector requires no credential to paste. It runs in the installing workspace’s app-instance context and propagates the caller’s Prisme.ai identity to the Storage backend over the platform’s cross-workspace forward-auth mechanism: every call inherits the user × workspace permissions of whoever triggered it, and the Storage backend enforces its own RBAC bindings on top. Agents are identified by the capability Scope context_id,agent_id,user_id; credentials are resolved server-side.

Files & Downloads

Upload by URL or bytes, list, download, share and delete files in workspace-scoped storage.

Vector Stores & RAG

Create vector stores, attach files (by file_id or URL), trigger reindex, run semantic search, monitor crawling.

Access, Keys & Skills

Grant/revoke RBAC bindings per principal, create and rotate per-store API keys, manage reusable agent skills.

Who is this for?

This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.

Agent builder

You build agents in Agent Factory and want them to manage files, vector stores and RAG. → Agent builder tab.

Platform admin

You run the platform and want to expose Storage as a reusable capability once for everyone. → Platform admin setup accordion below.

Workspace builder

You write Builder automations (DSUL) that call Storage instructions directly. → Workspace builder tab.

Prerequisites

A Prisme.ai workspace with the Prisme.ai Storage app installed.
The Storage backend ships pre-wired to the current environment (sandbox or prod) — there is no baseUrl, service URL or API token to configure. The connector resolves the Storage workspace via slug:storage and forwards the caller’s authentication automatically.
The end user (or agent’s calling user) must hold the appropriate role on the target vector store / file:
- viewer — read files, list vector stores, run semantic search.
- contributor — add/remove files in a vector store, trigger recrawls.
- owner — manage access bindings, API keys and skills; delete vector stores.
- admin (platform admin) — admin.getStats, admin.healthCheck, cross-workspace listings (scope=all).
For URL-based ingestion (files.upload with url=…, vectorStoreFiles.add with url=…), the URL must be reachable from the Storage backend (a public URL or a Prisme.ai share_token).

Platform admin (Governance) — one-time platform setup

No platform-level credential. This connector carries no third-party API key — each workspace installs the app and the caller’s Prisme.ai identity is forwarded to the Storage backend automatically. There is nothing to register in Studio Secrets and no per-tenant credential to provision.

The only optional one-time task is to expose Storage as a reusable capability in AI Governance, so agent builders can enable it from the capability picker instead of pasting an MCP endpoint URL.

Declare the capability in AI Governance

Open AI Governance > Capabilities

Create (or edit) a Prisme.ai Storage capability.

Point it at the MCP endpoint

Set the capability’s MCP server URL to the connector’s MCP Endpoint (read from the installed app instance), and set its Scope to:

context_id,agent_id,user_id

The agent_id and user_id in the scope are what let the connector identify the calling agent and forward the user’s identity to the Storage backend.

Make it available to agent builders

Once created, the capability appears in the capability picker for agent builders in your organization. Access to the catalog follows your organization’s existing roles; there is no per-capability role grant for this connector.

Smoke-test

From an agent that has the capability, ask it to list vector stores or files. The call runs as the agent’s user, and the Storage backend returns only the resources that user can see.

Declaring the capability makes the connector available; it does not by itself authorize a specific agent against any data. Authorization is enforced by the Storage backend’s own RBAC bindings, evaluated against the forwarded caller identity — a user (or agent’s user) only ever sees the stores and files they hold a role on. There is no OAuth auth-config JSON to attach in Governance: authentication is the forwarded Prisme.ai identity, not a per-user OAuth flow.

Agent builder (Agent Factory)
Workspace builder (DSUL)

Agent builder

Goal: let an agent you build in Agent Factory manage files, vector stores and RAG through the Storage MCP tools.

Before an agent can call the connector, a Workspace builder must have installed the Prisme.ai Storage app in a workspace (see the Workspace builder tab) — or a Platform admin must have published the capability in AI Governance (see the Platform admin setup accordion above).

This connector runs in the tenant app-instance context and forwards the caller’s Prisme.ai identity to the Storage backend. Your agent is identified by the agent_id and user_id that Agent Factory injects through the capability Scope; the Storage backend then enforces its own RBAC bindings against that user — there is no credential for the agent to hold or paste.

Get the MCP endpoint

Install the Prisme.ai Storage app in your workspace (see the Workspace builder tab) and copy its MCP Endpoint from the app instance configuration. If a Platform admin already published the capability, you can skip straight to the capability picker.

Add the capability to your agent

In your agent, add a capability pointing at the MCP Endpoint URL (or pick the published Prisme.ai Storage capability from the catalog), and set its Scope to:

context_id,agent_id,user_id

The agent_id lets the connector identify the calling agent; user_id is what propagates the caller’s identity to the Storage backend so its RBAC applies. Without user_id in the scope, calls run anonymously and the backend rejects them.

Use it

Ask the agent to manage files or knowledge — it calls the Storage tools, and every call is scoped to what the calling user is allowed to see.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent must know the tools exist and when to reach for them. Copy-pasteable starter:

You have access to the Prisme.ai Storage MCP server. Use it whenever the user asks to manage files (upload, list, download), vector stores (create, list, search), attach documents to a knowledge base, trigger a recrawl, manage RBAC bindings or per-store API keys. Calls run with the user's identity, so the user only sees stores and files they have access to. Always confirm with the user before destructive actions (files.delete, vectorStores.delete, access.revoke, apiKeys.revoke).

Refine the trigger keywords (resource names, business domains, typical user phrasings) so the agent reliably picks up the right intent in your context.

Legacy AI Knowledge agents (no native MCP picker): add the connector under Advanced > Tools > MCP and paste the MCP Endpoint URL. The agent’s identity is still propagated so the Storage backend can resolve the caller’s RBAC.

Available Tools

The MCP server exposes 8 entity-level tools, each with an action argument that selects the operation. Every tool also accepts an outputFormat argument (verbose default / structured / both).

`files`

Tool	Description
`files`	Storage files. Actions: `list` (filter by `conversation_id`, `purpose`, `status`), `upload` (from a public URL or raw bytes), `get` (by `file_id`), `delete`, `download` (optionally via a `share_token`).

`vectorStores`

Tool	Description
`vectorStores`	Vector stores (RAG indexes). Actions: `list` (`scope` = `own`/`shared`/`all`), `create` (`name` + `embedding` object `{model, dimensions?}`, optional `chunking_strategy` object), `get`, `update`, `delete` (removes all files/chunks), `search` (`query` ≤2048 chars, optional `max_num_results`, `filters`, `ranking_options`), `reindexAll`, `getAdminUrl` (pure URL formatter, no HTTP call).

`vectorStoreFiles`

Tool	Description
`vectorStoreFiles`	Files attached to a vector store. Actions: `list`, `add` (by `file_id` preferred, or `url` for backend ingestion; accepts `tags`, `metadata`, `force_recrawl`, `file_name`, `mime_type`, `headers`), `get`, `update`, `delete`, `getChunks` (debug), `reindex`.

`crawling`

Tool	Description
`crawling`	Web-crawling for a vector store. Actions: `getStatus`, `recrawl` (one or more `websites`), `getSourceCounts` (per-source page counts).

`access`

Tool	Description
`access`	RBAC access bindings on a vector store. Actions: `list`, `grant` (`principal_type`, `principal_id`, `role`), `update` (change role), `revoke`.

`apiKeys`

Tool	Description
`apiKeys`	Per-vector-store API keys. Actions: `list`, `create` (`name`, optional `slug`, `permissions`, `expiresAt`), `revoke`, `rotate` (mints a new secret, revokes the old one).

`skills`

Tool	Description
`skills`	Reusable agent skills (instructions + tools). Actions: `list` (optional `search`), `create` (`name`, `instructions`, optional `tools`), `get`, `update`, `delete`.

`admin`

Tool	Description
`admin`	Admin-only diagnostics. Actions: `getStats` (aggregate over `own`/`shared`/`all`), `healthCheck` (end-to-end).

Output Formats

Every tool accepts an outputFormat argument that controls the MCP response shape:

verbose (default) — human-readable text optimized for LLM consumption.
structured — machine-readable JSON in structuredContent.
both — the structured payload, with its JSON also rendered as text.

Tool Details

`vectorStores` (action: `create`)

{
  "name": "vectorStores",
  "arguments": {
    "action": "create",
    "name": "Customer Support KB",
    "description": "Searchable knowledge base for the support team",
    "embedding": {
      "model": "text-embedding-3-large",
      "dimensions": 3072
    },
    "chunking_strategy": { "type": "auto" }
  }
}

Parameter	Required	Description
`action`	Yes	Must be `create`.
`name`	Yes	Display name of the store.
`embedding`	Yes	Object `{ model, dimensions? }` — the embedding model. Never pass a string.
`description`	No	Free-text description.
`chunking_strategy`	No	Object `{type: "auto"}` (default) or `{type: "static", max_chunk_size_tokens, chunk_overlap_tokens}`.
`provider`	No	Vector index backend (`elasticsearch`/`opensearch`/`mock`) — NOT the embedding provider. Omit for the workspace default.

`vectorStoreFiles` (action: `add`)

{
  "name": "vectorStoreFiles",
  "arguments": {
    "action": "add",
    "vector_store_id": "vs_01H...",
    "file_id": "file_01H...",
    "tags": ["onboarding", "v2"],
    "metadata": { "owner": "support-team", "year": 2026 }
  }
}

Parameter	Required	Description
`action`	Yes	Must be `add`.
`vector_store_id`	Yes	Target vector store.
`file_id`	No	Existing file to attach. Either `file_id` OR `url` must be set.
`url`	No	Public URL — the backend ingests the file. Note: URL ingestion does not honor `file_name`; for filename control, upload first via `files.upload` and pass `file_id`.
`tags`	No	List of free-text tags for filtering at search time.
`metadata`	No	Structured metadata stored on the chunk.
`force_recrawl`	No	Re-ingest the URL even if a previous crawl was cached (also pass the original `url`).

`vectorStores` (action: `search`)

{
  "name": "vectorStores",
  "arguments": {
    "action": "search",
    "vector_store_id": "vs_01H...",
    "query": "How do I reset my password?",
    "max_num_results": 5,
    "filters": { "key": "year", "type": "eq", "value": 2026 }
  }
}

Parameter	Required	Description
`action`	Yes	Must be `search`.
`vector_store_id`	Yes	Target vector store.
`query`	Yes	Natural-language query (max 2048 chars).
`max_num_results`	No	Number of chunks to return.
`filters`	No	Elasticsearch-like metadata filter, e.g. `{key, type: "eq", value}` or `{type: "and", filters: [...]}`.
`ranking_options`	No	Object, e.g. `{score_threshold: 0.5}`.

`access` (action: `grant`)

{
  "name": "access",
  "arguments": {
    "action": "grant",
    "vector_store_id": "vs_01H...",
    "principal_type": "group",
    "principal_id": "grp_01H...",
    "role": "contributor"
  }
}

Parameter	Required	Description
`action`	Yes	Must be `grant`.
`vector_store_id`	Yes	Target vector store.
`principal_type`	Yes	`user`, `group` or `apiKey`.
`principal_id`	Yes	ID of the principal.
`role`	Yes	`viewer`, `contributor` or `owner`.

`apiKeys` (action: `create`)

{
  "name": "apiKeys",
  "arguments": {
    "action": "create",
    "vector_store_id": "vs_01H...",
    "name": "integration-test-suite",
    "slug": "qa-tests",
    "permissions": ["vector_store:read", "vector_store:search"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }
}

Parameter	Required	Description
`action`	Yes	Must be `create`.
`vector_store_id`	Yes	Target vector store.
`name`	Yes	Human-readable key name.
`slug`	No	Stable identifier (recommended for traceability).
`permissions`	No	List of scopes the key may call. Default = same as the creator’s role.
`expiresAt`	No	RFC3339 timestamp. Omit for non-expiring keys.

The plaintext API-key secret is returned only at creation time. Store it securely; the platform keeps only a hash.

Workspace builder

Installation

Go to Apps in your workspace
Search for Prisme.ai Storage and install it
Open the app instance configuration — only the MCP endpoint is surfaced, and it is auto-populated on install. There is no credential to enter.

Configuration

Field	Description
MCP Endpoint	Auto-populated on install — URL of the MCP endpoint for this app instance.

There is no third-party credential to configure. The connector forwards the caller’s Prisme.ai identity to the Storage backend on every call, and the backend enforces its own RBAC bindings.

Auth mode	What you provide	Best for
Forward-auth (default)	Nothing — the caller’s user × workspace identity is propagated automatically over cross-workspace forward-auth.	All standard use; calls run with the caller’s permissions.
`accessToken` override	An explicit Storage token passed per call via the `accessToken` argument.	Server-to-server flows that must act as a specific principal rather than the caller.

The connector is pre-wired to the Storage backend of the current environment (sandbox or prod) via slug:storage — no baseUrl to set. Anonymous calls (no forwarded identity and no accessToken) are rejected by the Storage backend.

Available Instructions

Every instruction resolves identity from the caller’s authenticated request. Vector-store-scoped operations target a vector_store_id; file operations take a file_id; cross-store operations take a scope (own, shared, or all for admins).

Files

Instruction	Description	Returns
`listFiles`	List files; optional `conversation_id`, `purpose`, `status`, `limit`, `page`.	`{ files: [{ id, name, purpose, status, … }], page }`
`uploadFile`	Upload a file from a public `url` or raw `bytes`; `purpose`, `file_name`, `mime_type`.	`{ file_id, name, purpose, status }`
`getFile`	Retrieve file metadata by `file_id`.	`{ id, name, purpose, status, … }`
`deleteFile`	Delete a file by `file_id`.	Empty (HTTP 204)
`downloadFileContent`	Download content by `file_id`; optional `redirect`, `share_token`.	File bytes (or a redirect URL).

Vector Stores

Instruction	Description	Returns
`listVectorStores`	List stores; `scope` (`own`/`shared`/`all`), `pageSize`, `page`, `status`, `agent_id`, `include_agents`.	`{ vector_stores: [{ id, name, status }], page }`
`createVectorStore`	Create a store; `name` + `embedding` object `{model, dimensions?}`; optional `chunking_strategy`, `metadata`, `provider`.	`{ id, name, embedding, status }`
`getVectorStore`	Retrieve a store by `vector_store_id`.	`{ id, name, description, embedding, status }`
`updateVectorStore`	Update `name`, `description`, `metadata`, `expires_after`, `chunking_strategy`.	`{ id, name, … }`
`deleteVectorStore`	Delete a store and all its files/chunks.	Empty (HTTP 204)
`searchVectorStore`	Semantic search; `query` (≤2048 chars), optional `max_num_results`, `filters`, `ranking_options`, `rewrite_query`.	`{ data: [{ score, content, metadata }] }`
`reindexAllVectorStoreFiles`	Re-index every file in the store.	`{ status }`
`getVectorStoreAdminUrl`	Format a deep-link to the store’s admin page (no HTTP call).	`{ url }`

Vector Store Files

Instruction	Description	Returns
`listVectorStoreFiles`	List files in a store; `vector_store_id` + optional `status`, `limit`, `page`, `agent_id`.	`{ files: [{ id, name, status }], page }`
`addFileToVectorStore`	Attach a file by `file_id` (preferred) OR `url`; `tags`, `metadata`, `force_recrawl`, `file_name`, `mime_type`, `headers`.	`{ file_id, status }`
`getVectorStoreFile`	Retrieve a vector-store file’s metadata by `vector_store_id` + `file_id`.	`{ id, name, status, tags, metadata }`
`updateVectorStoreFile`	Update a vector-store file’s `tags` / `metadata`.	`{ id, tags, metadata }`
`deleteVectorStoreFile`	Detach (and delete) a file from a store.	Empty (HTTP 204)
`getVectorStoreFileChunks`	Return the embedded chunks of a file (debug); `limit`, `offset`.	`{ chunks: [{ content, metadata }] }`
`reindexVectorStoreFile`	Re-embed a single file; optional `force`.	`{ status }`

Web Crawling

Instruction	Description	Returns
`getCrawlStatus`	Get the current crawl status of a store by `vector_store_id`.	`{ status, sources: [...] }`
`recrawlWebSources`	Trigger a recrawl of one or more `websites`.	`{ status }`
`getWebSourceCounts`	Get per-source page counts.	`{ counts: [{ url, pages }] }`

Access (RBAC)

Instruction	Description	Returns
`listVectorStoreAccess`	List RBAC bindings on a store; `limit`, `page`.	`{ bindings: [{ id, principal_type, principal_id, role }] }`
`grantVectorStoreAccess`	Grant access; `principal_type` (`user`/`group`/`apiKey`), `principal_id`, `role` (`viewer`/`contributor`/`owner`).	`{ id, role }`
`updateVectorStoreAccess`	Change the role of an existing binding.	`{ id, role }`
`revokeVectorStoreAccess`	Remove a binding.	Empty (HTTP 204)

API Keys

Instruction	Description	Returns
`listAPIKeys`	List API keys on a store; `limit`, `page`.	`{ keys: [{ id, name, slug, permissions }] }`
`createAPIKey`	Create a key; `name`, optional `slug`, `permissions`, `expiresAt`.	`{ id, secret, name, permissions }` (secret returned once)
`revokeAPIKey`	Revoke a key by `key_id`.	Empty (HTTP 204)
`rotateAPIKey`	Mint a new secret and revoke the old one.	`{ id, secret }`

Skills

Instruction	Description	Returns
`listSkills`	List reusable agent skills; optional `search`, `pageSize`, `page`.	`{ skills: [{ id, name, display_name }] }`
`createSkill`	Create a skill; `name`, `instructions`, optional `display_name`, `description`, `tools`.	`{ id, name, instructions }`
`getSkill`	Retrieve a skill by `skill_id`.	`{ id, name, instructions, tools }`
`updateSkill`	Update a skill’s `name`, `display_name`, `description`, `instructions`, `tools`.	`{ id, … }`
`deleteSkill`	Delete a skill by `skill_id`.	Empty (HTTP 204)

Admin

Instruction	Description	Returns
`getStorageStats`	Aggregate stats over `scope` (`own`/`shared`/`all`) — admin only.	`{ stores, files, chunks, … }`
`healthCheck`	End-to-end backend health check — admin only.	`{ status, checks: [...] }`

Returns shows the shape of the operation output. Calls run with the caller’s identity; the Storage backend rejects anonymous calls.

DSUL Examples

Upload a file from a URL and add it to a vector store:

- Prisme.ai Storage.files:
    action: upload
    url: 'https://example.com/whitepapers/q2-results.pdf'
    purpose: 'rag'
    file_name: 'q2-results.pdf'
    mime_type: 'application/pdf'
  output: uploaded
- Prisme.ai Storage.vectorStoreFiles:
    action: add
    vector_store_id: '{{knowledgeBaseId}}'
    file_id: '{{uploaded.file_id}}'
    tags:
      - quarterly-report
      - q2
    metadata:
      source: 'corporate-whitepapers'
      year: 2026

Create a vector store and grant access to a team:

- Prisme.ai Storage.vectorStores:
    action: create
    name: 'Customer Support KB'
    description: 'Searchable knowledge base for the support team'
    embedding:
      model: 'text-embedding-3-large'
      dimensions: 3072
    chunking_strategy:
      type: 'auto'
  output: store
- Prisme.ai Storage.access:
    action: grant
    vector_store_id: '{{store.id}}'
    principal_type: 'group'
    principal_id: '{{supportTeamGroupId}}'
    role: 'contributor'

Run a semantic search:

- Prisme.ai Storage.vectorStores:
    action: search
    vector_store_id: '{{knowledgeBaseId}}'
    query: '{{user.question}}'
    max_num_results: 5
    filters:
      key: 'year'
      type: 'eq'
      value: 2026
  output: hits

Trigger a recrawl after web sources changed:

- Prisme.ai Storage.crawling:
    action: recrawl
    vector_store_id: '{{knowledgeBaseId}}'
    websites:
      - 'https://docs.example.com'
      - 'https://blog.example.com'

Issue a per-store API key for an external client:

- Prisme.ai Storage.apiKeys:
    action: create
    vector_store_id: '{{knowledgeBaseId}}'
    name: 'integration-test-suite'
    slug: 'qa-tests'
    permissions:
      - 'vector_store:read'
      - 'vector_store:search'
    expiresAt: '2026-12-31T23:59:59Z'
  output: created

Error Handling

HTTP code	Meaning	Typical cause
`400`	Bad Request	Missing required field (e.g. `embedding` on `createVectorStore`), invalid `principal_type`, malformed metadata filter.
`401`	Unauthorized	The forward-auth chain did not propagate the caller’s identity. The Storage backend rejects anonymous calls.
`403`	Forbidden	The caller lacks the required role on the target store/file (e.g. `viewer` cannot add files; only `owner` can grant access).
`404`	Not Found	Vector store / file / binding / skill does not exist.
`409`	Conflict	Duplicate slug / unique-property collision (e.g. an API key with the same slug already exists).
`429`	Rate Limited	Storage backend quota exceeded — back off and retry.
`500` / `503`	Server Error	Transient backend failure — retry with exponential backoff.

Common Issues

“The calling agent could not be identified” — The MCP capability Scope does not declare agent_id / user_id, so Agent Factory never injects the caller identity. Set the Scope to context_id,agent_id,user_id on the capability. “Anonymous request rejected” (401) — The caller’s Prisme.ai identity did not make it through to the Storage backend. This usually means the call is being made from a tool client that does not propagate the workspace identity. Use the Agent Factory capability or call from a DSUL automation — both forward identity correctly — or pass an explicit accessToken override. Forbidden on a store you can see (403) — Listing a store does not imply write access. The operation requires a higher role (e.g. contributor to add files, owner to grant access or manage keys). Ask the store owner to grant the right binding via access.grant. addFileToVectorStore ignored my file_name when using url — URL-based ingestion of vector-store files drops the file_name argument. For filename control, upload the file first via files.upload and then add it via vectorStoreFiles.add with file_id. force_recrawl had no effect — Also pass the original url argument; the backend keys recrawl identity off the URL, not the file_id. Empty list when listing vector stores — By default listVectorStores returns only scope: own. Add scope: shared to include stores shared with you, or scope: all if you are a platform admin.

Files & Downloads

Vector Stores & RAG

Access, Keys & Skills

​Who is this for?

Agent builder

Platform admin

Workspace builder

​Prerequisites

​Declare the capability in AI Governance

​Agent builder

​Brief the agent in its system prompt

​Available Tools

​files

​vectorStores

​vectorStoreFiles

​crawling

​access

​apiKeys

​skills

​admin

​Output Formats

​Tool Details

​vectorStores (action: create)

​vectorStoreFiles (action: add)

​vectorStores (action: search)

​access (action: grant)

​apiKeys (action: create)

​Workspace builder

​Installation

​Configuration

​Available Instructions

​Files

​Vector Stores

​Vector Store Files

​Web Crawling

​Access (RBAC)

​API Keys

​Skills

​Admin

​DSUL Examples

​Error Handling

​Common Issues

​External Resources

RAG & Vector Stores

Tool Agents

Who is this for?

Prerequisites

Declare the capability in AI Governance

Agent builder

Brief the agent in its system prompt

Available Tools

`files`

`vectorStores`

`vectorStoreFiles`

`crawling`

`access`

`apiKeys`

`skills`

`admin`

Output Formats

Tool Details

`vectorStores` (action: `create`)

`vectorStoreFiles` (action: `add`)

`vectorStores` (action: `search`)

`access` (action: `grant`)

`apiKeys` (action: `create`)

Workspace builder

Installation

Configuration

Available Instructions

Files

Vector Stores

Vector Store Files

Web Crawling

Access (RBAC)

API Keys

Skills

Admin

DSUL Examples

Error Handling

Common Issues

External Resources