Picsha AI MCP Server

Overview

The Picsha AI API includes a fully functional Model Context Protocol (MCP) server natively integrated into our platform. This allows your custom AI agents, assistants, and LLM workflows to directly interface with your Picsha instance over Server-Sent Events (SSE).

By connecting to the Picsha MCP Server, your AI agents can instantly search, retrieve, and process your organization's digital assets without you having to build custom API wrappers or prompt definitions.

Connection Details

The MCP server is fully managed and available alongside your standard Picsha API instance.

Endpoint URL: https://api.picsha.ai/v1/mcp/sse (or your custom enterprise API domain)
Transport: Server-Sent Events (SSE)

Authentication

The MCP endpoint uses the same robust authentication as the core Picsha AI API. You must provide your Picsha API key as a Bearer token in the Authorization header when establishing the SSE connection.

GET /v1/mcp/sse HTTP/1.1
Host: api.picsha.ai
Authorization: Bearer <YOUR_PICSHA_API_KEY>

Multi-Tenancy & User Isolation (For B2B2C Apps)

If you are building an AI agent that serves multiple users (for example, a Slack bot or a customer-facing SaaS application), you must ensure the agent only accesses assets belonging to the specific user making the request.

Picsha AI natively supports strict multi-tenant isolation at the transport layer. You do not need to build complex mapping logic or modify your LLM prompts. Instead, you simply start the MCP Server session with the PICSHA_EXTERNAL_USER_ID environment variable.

PICSHA_API_KEY="..." PICSHA_EXTERNAL_USER_ID="user_123" npx @picsha-ai/mcp-server

(If you are connecting via custom SSE clients instead of npx, append the x-external-user-id: <user_id> HTTP header during connection).

When this value is present:

Isolated Sandboxing: The Picsha backend transparently overrides OpenSearch and Postgres database filters so the AI agent can only search, view, or modify files owned by that specific user.
Invisible Enforcement: The LLM tools functionally operate the same, but mathematically cannot exceed the boundaries of that single tenant.

If PICSHA_EXTERNAL_USER_ID is omitted, the MCP Server defaults to a Fail-Closed state (403 Forbidden) to protect multi-tenant B2B2C deployments from accidental data exposure. If you are building an internal tool and genuinely need full organization access, you must explicitly set PICSHA_ALLOW_ORG_ADMIN=true instead.

Integrating with AI Agents

Using the MCP TypeScript / Python SDKs

If you are building your own AI agent (for example, using LangChain, defining custom LLM tool chains, or a custom Node/Python application), you can connect to the Picsha MCP server using the official MCP client SDKs.

TypeScript Example:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://api.picsha.ai/v1/mcp/sse"),
  {
    headers: {
      "Authorization": `Bearer ${process.env.PICSHA_API_KEY}`
    }
  }
);

const mcpClient = new Client(
  { name: "my-ai-agent", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

await mcpClient.connect(transport);

// View available Picsha tools for your LLM
const tools = await mcpClient.request({ method: "tools/list" });
console.log(tools);

Claude Desktop Integration

Claude Desktop primarily expects local MCP servers using stdio transport. To bridge Claude Desktop to our remote SSE server seamlessly, we provide a zero-config bridge utility.

Open Claude Desktop.
Go to Settings > Developer and click Edit Config.
Add the following entry to your claude_desktop_config.json file:

{
  "mcpServers": {
    "picsha-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@picsha-ai/mcp-bridge",
        "https://api.picsha.ai/v1/mcp/sse"
      ],
      "env": {
        "PICSHA_API_KEY": "<YOUR_PICSHA_API_KEY>"
      }
    }
  }
}

Don't have an API key? Generate one from your Picsha Admin Dashboard.

Save the file and restart Claude Desktop. You should now see the Picsha hammer icon 🔨 in your prompt bar, indicating the tools are successfully connected!

The Agentic Workflow (How to talk to Claude)

Now that Claude is connected, you can use natural language to search, generate, and organize your files.

Recommended Context Prompt To get the best results from Claude, start a new chat with the following context prompt. This ensures Claude knows exactly how to utilize the Picsha tools you've provided.

"You are my Picsha Media Assistant. You have direct access to my organization's Digital Asset Management library via MCP tools. When I ask for images, use search_assets with mode: \"ai\" to find them semantically. When I ask for alterations (like background removal or MIMI edits), use render_asset_preview to perform the transformation and show me the resulting image preview inline while also providing the final cdnUrl. Keep my workspace organized by using create_dam_group and link_assets for variations."

Example Prompts to Try

1. Semantic Search & Discovery

You: "Find me photos of people wearing red hats enjoying the outdoors, then summarize what's happening in the top 3 results."
What Claude Does: Calls search_assets(query: "people wearing red hats outdoors", mode: "ai"), reads the rich AI descriptions attached to the results, and intelligently summarizes them.

2. On-the-fly Image Manipulation

You: "Grab that sunset photo we just uploaded, remove the background, and crop it to a 16:9 aspect ratio."
What Claude Does: First searches to find the sunset photo ID. Then calls render_asset_preview(id: "550e8400-e29b-41d4-a716-446655440000", params: "bg_rem=true&ar=16:9") to dynamically generate the asset. Claude visually returns the finished image directly into the chat interface for your review, and provides the finalized 4K delivery CDN link.

3. Intelligent Organization

You: "Gather all photos related to the Q3 Marketing Campaign and put them into a new folder."
What Claude Does: Executes a semantic search for related campaign assets. Calls create_dam_group(name: "Q3 Campaign"), adds the retrieved IDs to the group, and confirms the organization structure.

4. Background Moderation Tracking

You: "Can you trigger an Anthropic Claude re-analysis on that blurry document and let me know when the summary is ready?"
What Claude Does: Calls reanalyze_asset on the document, then utilizes the get_job_status tool to silently poll the background worker. Once the Amazon Bedrock summary generation completes, Claude pings you back with the summarized text.

Available Tools

The embedded MCP server currently exposes the following tools:

1. `search_assets`

Search for assets in the Picsha AI platform. Natively supports semantic/vector search for natural language queries.

query (string, required): The search query to find assets.
mode (string, optional): The search mode to use. Set to "ai" to enable hybrid semantic vector search using natural language (e.g., "people wearing red hats"). Defaults to "standard" for simple tag/text matching.
threshold (number, optional): Minimum relevance score threshold (default: 0.6).

2. `get_asset`

Retrieve detailed metadata for a specific asset.

id (string, required): The unique ID of the asset to fetch metadata for.

3. `list_recent_assets`

Returns the most recently uploaded assets in chronological order.

limit (number, default: 10): Number of assets to retrieve limit.

4. `reanalyze_asset`

Triggers the Picsha AI processing pipeline for a given asset. This allows an agent to natively trigger intelligent summaries and automated tagging dynamically.

id (string, required): The unique ID of the asset.
config (object, optional): Object containing bool flags mimicking the ingest options (e.g. auto_summarize, auto_tag, vectorize, location_lookup, adaptive_stream).

5. `get_presigned_upload_url`

Returns a secure, short-lived AWS S3 Presigned URL that the AI agent can use locally via standard HTTP PUT to upload binary resources to the Picsha platform securely without passing heavy base64 strings over the MCP JSON layer.

filename (string, required): Original filename (e.g. image.jpg).
contentType (string, required): MIME type of the file (e.g. image/jpeg).

6. `trigger_url_ingest`

Allows an agent to ingest a file from a public web URL. By passing a URL, the Picsha ingest worker downloads the file directly to S3 and automatically processes it.

url (string, required): Public URL for the worker to download the asset from.
filename (string, optional): Explicit filename to save.
config (object, optional): Processing configuration (e.g. { auto_summarize: true }).
tags (array, optional): Array of tags to apply to the asset natively upon upload.
metadata (object, optional): JSON object of structured metadata to apply natively upon upload.

7. `generate_render_url`

Generates a signed delivery URL for an asset with applied transformations or AI overrides. Provides immediate access to Picsha's visual manipulation engine without duplicating the underlying asset.

id (string, required): The unique ID of the asset.
transformations (object, required): A key-value pair of transformation parameters. Supports standard parameters (e.g. w, h, ar, fmt), forced downloads (e.g. dl: "true" or dl: "custom.jpg"), and generative AI parameters (e.g. bg_rem: "true", mimi: "remove person and add a sunset scene", mimi_mode: "lite", upscale: "4k", mimi_bg: "misty alpine lake").

8. `update_asset`

Allows agents to act as automated curators by updating asset metadata and tags.

id (string, required): The unique ID of the asset.
tags (array, optional): Array of strings to append as tags. To remove tags, prefix the string with a hyphen (e.g. ["-old_tag", "new_tag"]).
metadata (object, optional): Custom key-value dictionary to attach to the asset.

9. `delete_asset`

Moves an asset into a 30-day "Trash" state (Soft Delete). The asset will no longer appear in search results or delivery endpoints, but can be restored via the dashboard. This fail-safe protects against prompt injection or rogue agent behaviors.

id (string, required): The unique ID of the asset.
force (boolean, optional): If true, attempts a permanent hard-delete. Note: This will be rejected (403 Forbidden) unless the agent is authenticated with an Organization Admin Secret Key.

10. `moderate_asset`

Allows specialized AI agents to handle moderation workflows by approving or rejecting flagged assets.

id (string, required): The unique ID of the asset.
action (string, required): The moderation action. Must be "approve" or "reject".

11. `create_dam_group`

Creates a collection or folder to structurally organize assets.

name (string, required): The name of the collection/folder.
description (string, optional): A description for the group.
assetIds (array, optional): Initial array of asset IDs to add to this group.

12. `link_assets`

Explicitly defines a relationship between two assets, useful for linking AI-generated variants to their originals.

sourceId (string, required): The asset ID of the parent or source asset.
targetId (string, required): The asset ID of the variation, derived, or correlated asset.
relationshipType (string, required): Description of the link (e.g., "REPLACES", "VARIATION", "CONVERTED").

13. `escalate_to_support`

Use this tool ONLY when you need to log a feature request, report a documentation gap, or escalate an issue to the engineering team. This will actually send an email to support@picsha.ai.

subject (string, required): The subject of the escalation email.
headline (string, required): A short, punchy headline for the email.
message (string, required): The full summary of the request, formatted nicely.

14. `render_asset_preview`

Generates a dynamic preview of an asset with applied transformations or AI overrides, returning the visual base64 image bytes natively to the agent.

id (string, required): The unique ID of the asset.
params (string, optional): A query string of transformation parameters (e.g. bg_rem=true&mimi=sunset or mimi=sunset&mimi_mode=lite for a faster 1K preview render).
maxDim (number, optional): The maximum dimension in pixels to cap the preview at (default: 768).
timeoutMs (number, optional): Max time to block waiting for cold generation.

15. `poll_render`

Checks the status of an asynchronous generation started by render_asset_preview if the initial request times out and returns pending.

jobId (string, required): The async job ID returned by a pending render response.
timeoutMs (number, optional): Bounded wait to check for completion.

16. `get_job_status`

Checks the status of an asynchronous background worker task (such as Amazon Bedrock summarization or MediaConvert video transcoding) initialized by reanalyze_asset.

jobId (string, required): The unique ID of the background job.

Picsha AI MCP Server

Overview

Connection Details

Authentication

Multi-Tenancy & User Isolation (For B2B2C Apps)

Integrating with AI Agents

Using the MCP TypeScript / Python SDKs

Claude Desktop Integration

The Agentic Workflow (How to talk to Claude)

Example Prompts to Try

Available Tools

1. search_assets

2. get_asset

3. list_recent_assets

4. reanalyze_asset

5. get_presigned_upload_url

6. trigger_url_ingest

7. generate_render_url

8. update_asset

9. delete_asset

10. moderate_asset

11. create_dam_group

12. link_assets

13. escalate_to_support

14. render_asset_preview

15. poll_render

16. get_job_status