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 used either as a Builder app (automations call Storage instructions directly) or as a remote MCP server consumed by an AI agent. The connector 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 does not require a per-tenant API key. It propagates the caller’s identity to the Storage backend over the platform’s cross-workspace forward-auth mechanism: every call inherits the user × workspace permissions of the user who triggered it, and the Storage backend enforces its own RBAC bindings on top.

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

Prerequisites

A Prisme.ai workspace with the Prisme.ai Storage app installed.
The end user calling the connector must have 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, 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 (public URL or a Prisme.ai share_token).

This connector ships pre-wired to the Storage backend of the current environment (sandbox or prod). No baseUrl or service URL needs to be configured. The MCP server resolves the Storage workspace via slug:storage and forwards the caller’s authentication automatically.

Usage as App
Usage as MCP

Installation

Go to Apps in your workspace
Search for Prisme.ai Storage and install it
Open the app instance configuration — only the MCP endpoint and key are surfaced; both are auto-populated

Configuration

Field	Description
MCP Endpoint	Auto-populated on install — URL of the MCP endpoint for this instance
MCP API Key	Auto-populated on install — signed key used in the `mcp-api-key` header. Do not modify

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 (see Access below).

Available Instructions

Every instruction resolves identity from the caller’s authenticated request. All 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	Arguments
`listFiles`	`conversation_id`, `purpose`, `status`, `limit`, `page`
`uploadFile`	`url`, `purpose`, `file_name`, `mime_type`, `bytes`
`getFile`	`file_id`*
`deleteFile`	`file_id`*
`downloadFileContent`	`file_id`*, `redirect`, `share_token`

Vector Stores

Instruction	Arguments
`listVectorStores`	`scope` (`own`/`shared`/`all`), `pageSize`, `page`, `status`, `agent_id`, `include_agents`
`createVectorStore`	`name`, `description`, `embedding`, `chunking`, `metadata`
`getVectorStore`	`vector_store_id`*
`updateVectorStore`	`vector_store_id`*, `name`, `description`, `metadata`
`deleteVectorStore`	`vector_store_id`*
`searchVectorStore`	`vector_store_id`, `query`, `top_k`, `filters`, `include_metadata`
`reindexAllVectorStoreFiles`	`vector_store_id`*
`getVectorStoreAdminUrl`	`vector_store_id`*

Vector Store Files

Instruction	Arguments
`listVectorStoreFiles`	`vector_store_id`*, `status`, `limit`, `page`, `agent_id`
`addFileToVectorStore`	`vector_store_id`*, `file_id`, `url`, `tags`, `metadata`, `force_recrawl`, `file_name`, `mime_type`, `headers`, `agent_id`
`getVectorStoreFile`	`vector_store_id`, `file_id`
`updateVectorStoreFile`	`vector_store_id`, `file_id`, `tags`, `metadata`
`deleteVectorStoreFile`	`vector_store_id`, `file_id`
`getVectorStoreFileChunks`	`vector_store_id`, `file_id`, `limit`, `page`
`reindexVectorStoreFile`	`vector_store_id`, `file_id`

Web Crawling

Instruction	Arguments
`getCrawlStatus`	`vector_store_id`*
`recrawlWebSources`	`vector_store_id`*, `websites`
`getWebSourceCounts`	`vector_store_id`*

Access (RBAC)

Instruction	Arguments
`listVectorStoreAccess`	`vector_store_id`*, `limit`, `page`
`grantVectorStoreAccess`	`vector_store_id`, `principal_type`, `principal_id`, `role`
`updateVectorStoreAccess`	`vector_store_id`, `binding_id`, `role`*
`revokeVectorStoreAccess`	`vector_store_id`, `binding_id`

API Keys

Instruction	Arguments
`listAPIKeys`	`vector_store_id`*, `limit`, `page`
`createAPIKey`	`vector_store_id`, `name`, `slug`, `permissions`, `expiresAt`
`revokeAPIKey`	`vector_store_id`, `key_id`
`rotateAPIKey`	`vector_store_id`, `key_id`

Skills

Instruction	Arguments
`listSkills`	`search`, `pageSize`, `page`
`createSkill`	`name`, `display_name`, `description`, `instructions`, `tools`
`getSkill`	`skill_id`*
`updateSkill`	`skill_id`*, `name`, `display_name`, `description`, `instructions`, `tools`
`deleteSkill`	`skill_id`*

Admin

Instruction	Arguments
`getStorageStats`	`scope` (`own`/`shared`/`all`)
`healthCheck`	(none)

Arguments flagged with * are required. 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: '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}}'
    top_k: 5
    filters:
      year: 2026
    include_metadata: true
    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

The Prisme.ai Storage app ships with a built-in MCP server. Each app instance gets its own signed mcp-api-key that encodes the workspace ID — the MCP server forwards the caller’s Prisme.ai identity to the Storage backend on every tool call, so per-user RBAC bindings apply automatically.

Plug into an Agent Creator capability

Agents consume MCP servers directly through Agent Creator capabilities. This is the preferred way to expose the Storage backend to an agent.

Create or open a workspace

From the Prisme.ai console, create a new workspace (or open the one that will host the connector).

Install the Prisme.ai Storage app

Open the workspace Imports panel, search for Prisme.ai Storage and install it.

Copy the MCP endpoint and API key

On the app instance configuration page, copy the values of MCP Endpoint and MCP API Key — both are generated automatically on install.

Open Agent Creator

Switch to Agent Creator and open the agent you want to extend.

Add a capability

Add a new capability to the agent:

If a dedicated Storage capability exists — select it and paste the MCP API Key into the mcp-api-key field. The server URL is already wired.
Otherwise — select the generic custom_mcp capability, paste the MCP Endpoint into the Server URL field, then open the Headers field and add an mcp-api-key entry whose value is the MCP API Key copied earlier:
```
{
  "mcp-api-key": "your-mcp-api-key"
}
```

Save

The agent now has access to every Storage tool exposed by the MCP server, running as the calling user.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent also needs to know the MCP exists and when to reach for it. Add a short paragraph to the agent’s system prompt. 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 (deleteFile, deleteVectorStore, revokeAccess, revokeAPIKey).

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

Legacy MCP Install (Advanced > Tools)

Use this flow to plug the Storage MCP into an AI Knowledge agent that does not yet support the native MCP picker.

Install the Prisme.ai Storage app

Install the app in the same workspace as your agent. Once installed, mcpEndpoint and mcpApiKey are auto-populated.

Copy the MCP credentials

Open the app instance config and copy the values of MCP Endpoint and MCP API Key.

Open your AI Knowledge project

Navigate to Advanced > Tools.

Add an MCP tool

Click Add and select the MCP tab.

Fill in the endpoint

Paste the MCP Endpoint URL copied from the app instance.

Add the auth header

In the Headers field, add the signed API key:

{
  "mcp-api-key": "your-mcp-api-key"
}

Save

The agent can now list and call Storage tools through the MCP endpoint.

The signed mcp-api-key encodes the workspace ID and the central App secret. The MCP server forwards the caller’s identity (user × workspace) to the Storage backend via cross-workspace forward-auth — no third-party token is needed. Anonymous calls are rejected by the Storage backend.

Output Formats

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

verbose (default) — human-readable text for LLM consumption
structured — machine-readable JSON in structuredContent
both — both text and structured content

Available Tools

The MCP server exposes 8 entity-level tools (each with an action argument to select the operation).

`files`

Action	Description
`list`	List files (optionally filter by `conversation_id`, `purpose`, `status`)
`upload`	Upload a file from a public URL or raw bytes
`get`	Retrieve file metadata by `file_id`
`delete`	Delete a file
`download`	Download the file content (optionally via a `share_token`)

`vectorStores`

Action	Description
`list`	List vector stores. `scope` controls visibility (`own`, `shared`, `all` — admin only)
`create`	Create a vector store. Requires `name` and `embedding` (`{ model, dimensions? }`)
`get`	Retrieve a vector store by id
`update`	Update a vector store’s name, description or metadata
`delete`	Delete a vector store (and all its files)
`search`	Run a semantic search across the store with optional `filters` and `top_k`
`reindexAll`	Re-embed all files in the store
`getAdminUrl`	Return a deep-link to the store’s admin page in the platform UI

`vectorStoreFiles`

Action	Description
`list`	List files attached to a vector store
`add`	Attach a file by `file_id` (preferred) OR by `url` (the backend downloads it). Accepts `tags`, `metadata`, `force_recrawl`
`get`	Retrieve metadata of a vector-store file
`update`	Update a vector-store file’s tags / metadata
`delete`	Detach (and delete) a file from a vector store
`getChunks`	Return the embedded chunks of a file (for debugging)
`reindex`	Re-embed a single file

`crawling`

Action	Description
`getStatus`	Get the current crawl status of a vector store
`recrawl`	Trigger a recrawl of one or more web sources
`getSourceCounts`	Get per-source page counts

`access`

Action	Description
`list`	List RBAC bindings on a vector store
`grant`	Grant access to a principal (`user`, `group`, `apiKey`) with a role (`viewer`, `contributor`, `owner`)
`update`	Change the role of an existing binding
`revoke`	Remove a binding

`apiKeys`

Action	Description
`list`	List API keys on a vector store
`create`	Create an API key with `permissions` and optional `expiresAt`
`revoke`	Revoke an API key
`rotate`	Rotate an API key (mints a new secret and revokes the old one)

`skills`

Action	Description
`list`	List reusable agent skills
`create`	Create a skill (`instructions` + optional `tools`)
`get`	Retrieve a skill by id
`update`	Update a skill
`delete`	Delete a skill

`admin`

Action	Description
`getStats`	Aggregate stats over `own`, `shared` or `all` (admin only)
`healthCheck`	End-to-end health check (admin only)

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": "auto" }
  }
}

Parameter	Required	Description
`action`	✓	Must be `create`
`name`	✓	Display name of the store
`embedding`	✓	`{ model: string, dimensions?: number }` — embedding model to use
`description`	–	Free-text description
`chunking`	–	`{ strategy: "auto" \| "fixed", chunk_size?, overlap? }`
`metadata`	–	Arbitrary metadata attached to the store

`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`	✓	Must be `add`
`vector_store_id`	✓	Target vector store
`file_id`	–	Existing file to attach. Either `file_id` OR `url` must be set
`url`	–	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`	–	List of free-text tags for filtering at search time
`metadata`	–	Structured metadata stored on the chunk
`force_recrawl`	–	Re-ingest the URL even if it was crawled before

`vectorStores` (action: `search`)

{
  "name": "vectorStores",
  "arguments": {
    "action": "search",
    "vector_store_id": "vs_01H...",
    "query": "How do I reset my password?",
    "top_k": 5,
    "filters": { "year": 2026 },
    "include_metadata": true
  }
}

Parameter	Required	Description
`action`	✓	Must be `search`
`vector_store_id`	✓	Target vector store
`query`	✓	The natural-language query
`top_k`	–	Number of chunks to return (default 10)
`filters`	–	Metadata filters — e.g. `{ year: 2026, owner: "support-team" }`
`include_metadata`	–	Include chunk metadata in the response

`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`	✓	Must be `grant`
`vector_store_id`	✓	Target vector store
`principal_type`	✓	`user`, `group` or `apiKey`
`principal_id`	✓	ID of the principal
`role`	✓	`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`	✓	Must be `create`
`vector_store_id`	✓	Target vector store
`name`	✓	Human-readable key name
`slug`	–	Stable identifier (recommended for traceability)
`permissions`	–	List of scopes the key is allowed to call. Default = same as the creator’s role
`expiresAt`	–	RFC3339 timestamp. Omit for non-expiring keys

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

Error Handling

HTTP Status	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 does not have 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

“Not configured” — Should not normally happen for this connector since it carries no external credential. If you see it, reinstall the app instance to regenerate the MCP API key. “Invalid API key” (MCP) — The mcp-api-key header does not match the central app secret. Reinstall the app instance to regenerate a signed key. “Anonymous request rejected” (401) — The caller’s Prisme.ai identity did not make it through to the Storage backend. This usually means the MCP call is being made from a tool client that does not propagate the workspace JWT. Use the Agent Creator capability or call from a DSUL automation, both of which forward identity correctly. addFileToVectorStore ignored my file_name when using url — URL-based ingestion of vector-store files drops the file_name argument. If you need filename control, upload the file first via files.upload and then add it via vectorStoreFiles.add with file_id. force_recrawl had no effect — Make sure you 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.

Documentation Index

Files & Downloads

Vector Stores & RAG

Access, Keys & Skills

​Prerequisites

​Installation

​Configuration

​Available Instructions

​Files

​Vector Stores

​Vector Store Files

​Web Crawling

​Access (RBAC)

​API Keys

​Skills

​Admin

​DSUL Examples

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

​Create a vector store and grant access to a team

​Run a semantic search

​Trigger a recrawl after web sources changed

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

​Plug into an Agent Creator capability

​Legacy MCP Install (Advanced > Tools)

​Output Formats

​Available Tools

​files

​vectorStores

​vectorStoreFiles

​crawling

​access

​apiKeys

​skills

​admin

​Tool Details

​vectorStores (action: create)

​vectorStoreFiles (action: add)

​vectorStores (action: search)

​access (action: grant)

​apiKeys (action: create)

​Error Handling

​Common Issues

​External Resources

Storage backend overview

Tool Agents

Prerequisites

Installation

Configuration

Available Instructions

Files

Vector Stores

Vector Store Files

Web Crawling

Access (RBAC)

API Keys

Skills

Admin

DSUL Examples

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

Create a vector store and grant access to a team

Run a semantic search

Trigger a recrawl after web sources changed

Issue a per-store API key for an external client

Plug into an Agent Creator capability

Legacy MCP Install (Advanced > Tools)

Output Formats

Available Tools

`files`

`vectorStores`

`vectorStoreFiles`

`crawling`

`access`

`apiKeys`

`skills`

`admin`

Tool Details

`vectorStores` (action: `create`)

`vectorStoreFiles` (action: `add`)

`vectorStores` (action: `search`)

`access` (action: `grant`)

`apiKeys` (action: `create`)

Error Handling

Common Issues

External Resources