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 token 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_TOKEN>

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_TOKEN="..." 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 API defaults to Organization Administrative access, granting the agent full visibility across your entire organization's digital asset library.

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_TOKEN}`
    }
  }
);

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_TOKEN": "<YOUR_PICSHA_API_TOKEN>"
      }
    }
  }
}

Don't have an API token? 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 generate_render_url to provide me with the modified delivery links immediately. 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 generate_render_url(id: "sunset123", transformations: { "bg_rem": "true", "ar": "16:9" }) and returns the direct link to the finalized image.

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 Amazon Titan 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 Amazon Titan generative edits, Bedrock summaries, and Rekognition 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. `upload_asset`

Uploads a local file directly to the Picsha AI platform. This acts as a proxy, automatically determining the MIME type, fetching a pre-signed S3 URL, and executing the PUT request. Uploading immediately triggers the asynchronous picsha-ai-ingest pipeline.

filePath (string, required): Absolute path to the local file (e.g. /Users/name/images/photo.jpg).
filename (string, optional): Original filename to associate with the asset. Defaults to the file's basename.

6. `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).

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

8. `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").

9. `get_job_status`

Polls the execution status of asynchronous background processes or heavily generative workflows.

jobId (string, required): The unique identifier of the background job (returned from reanalyze_asset or other long-running tasks).

10. `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.

11. `delete_asset`

Permanently deletes an asset from the Picsha platform, organization buckets, and OpenSearch index.

id (string, required): The unique ID of the asset.

12. `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".

13. `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.

14. `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., "variation", "converted").

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. upload_asset

6. get_presigned_upload_url

7. trigger_url_ingest

8. generate_render_url

9. get_job_status

10. update_asset

11. delete_asset

12. moderate_asset

13. create_dam_group

14. link_assets