Connecting an AI assistant to freedam through the Model Context Protocol (MCP) turns your asset library into something an agent can actually work with. Instead of copy-pasting filenames into a chat window, you point an MCP-aware client — Claude, ChatGPT, or any other agent that speaks the protocol — at the server that ships inside the product, hand it a token, and the agent can search, fetch, upload, organize, and share assets on your behalf.

What it does

freedam includes a native MCP server. There is nothing extra to install or run — it is part of the application, served at /mcp/freedam on your instance. It exposes eleven tools that map to normal API capabilities:

• search-assets — natural-language search with hybrid full-text plus semantic ranking, and optional filters
• get-asset — fetch one asset by its global ID, with metadata, conversions, and rights
• update-asset-metadata — edit titles, descriptions, keywords, and structured metadata, with validation
• list-collections and create-collection — browse and create collections, including nested ones
• add-to-collection — add a list of assets to a collection in one call
• upload-assets — open an upload batch and stream files into it, optionally landing in a target collection
• create-share — generate a share link with expiration and access controls
• get-vocabularies — read controlled vocabularies and terms, so an agent picks valid values instead of inventing them
• bulk-update — apply field changes to many assets at once, tracked through an operation
• get-operation-status — poll a long-running operation for progress, errors, and result counts

That set covers real workflows: an agent can triage a fresh upload batch, fill in missing metadata against your vocabularies, sort assets into collections, and hand back a share link — all through schema-validated tool calls. There are no agent-only side doors; every tool corresponds to a capability the API already has.

How it works

The server is stateless and token-authenticated. You create an API token in Settings → API Tokens, choosing exactly the abilities (scopes) the agent should have, then configure your MCP client with the server URL and a Authorization: Bearer header:

{
    "mcpServers": {
        "freedam": {
            "url": "https://your-instance.example.com/mcp/freedam",
            "headers": { "Authorization": "Bearer YOUR_TOKEN" }
        }
    }
}

Because the server runs inside the product, every tool call goes through the same permission model as a human user. A token with read-only abilities cannot be talked into deleting an asset, no matter how creative the prompt. Every call also lands in the same audit trail as the rest of the API, so you can always see which token did what, when, and to which asset.

Good to know

• Scopes are enforced per tool. Tokens can never carry more privilege than the person who created them, and a missing scope means a refused call — not a silent fallback.
• Rate limits apply. MCP calls count against the same per-token budget of 60 requests per minute as REST calls, so a runaway agent loop hits the same ceiling as a runaway script.
• Tokens are shown once. Copy the token at creation time; only a hash is stored server-side. Revoke and reissue if you lose it.
• Self-hosted instances get the same server — it is part of the application, not a hosted add-on.

The MCP server sits on top of the same surface as the REST API, so anything an agent starts, a script can finish. Want to see it drive a real library? Try the demo.