MCP Server

The MCP Server feature allows you to connect your Freedam assets and data to AI assistants using the Model Context Protocol (MCP). By exposing specific "tools" to an AI, you enable it to see, search, and modify your digital assets directly from within its own interface.

This feature is designed for administrators who want to leverage Large Language Models (LLMs) to automate metadata tagging, asset discovery, and collection management. Instead of manually uploading files to an AI, the AI "reaches into" Freedam to perform tasks on your behalf.

Page Overview

• Purpose: To provide the connection details and configuration snippets required to link Freedam with AI platforms.
• When to use it: Use this page when setting up a new AI assistant (like Claude Desktop or ChatGPT) or when you need to audit which tools are currently exposed to AI agents.
• What you can do here:
  • Copy your unique MCP Endpoint URL.
  • View the number of available read-only and write-enabled tools.
  • Access configuration code for Claude Desktop, Claude Code, and OpenAI.
  • Browse the full list of tools and their descriptions.
  • Test the connection using a sample command-line request.

Page Layout

• Top bar: Displays the page title "MCP Server" and a brief description of the protocol.
• Stats Cards: A row of cards showing the MCP Endpoint URL, the count of available tools, and the protocol transport type (Streamable HTTP).
• Main area: A tabbed interface containing three sections: Integrations, Tools, and Test.
• Navigation Links: Direct links to the API Management page for generating the required authentication tokens.

Main Features

MCP Endpoint

• What it's for: This is the unique web address that AI assistants use to communicate with your Freedam instance.
• Typical use: You copy this URL and paste it into the "Connector" or "App" settings of your AI platform.
• Result: The AI platform establishes a secure bridge to your DAM.

Integration Snippets

• What it's for: Provides pre-formatted JSON configuration blocks for specific AI clients.
• Typical use: Copying the configuration for Claude Desktop to enable Freedam tools in your local AI application.
• Result: Eliminates manual coding by providing ready-to-use configuration files.

Tool Directory

• What it's for: Lists every capability currently exposed to the AI.
• Typical use: Checking if an AI has the "write" permission to edit metadata or if it is restricted to "read-only" searching.
• Result: Provides transparency into what actions an AI can perform on your data.
• Read-only tools (blue Eye icon) — the AI can look but not change:
  • Search assets (full-text and semantic search)
  • Get a single asset (all its details and metadata)
  • List collections
  • Get vocabularies (the controlled tag and category lists your team uses)
  • Get operation status (progress of a long-running upload or bulk job)
• Write tools (amber Pencil icon) — the AI can change or create data:
  • Upload assets
  • Update asset metadata
  • Bulk update (apply the same metadata change across many assets)
  • Create a collection
  • Add assets to a collection
  • Create a share link

Which of these the AI can actually use still depends on the permission groups on the token it was given. For example, an AI with a token that only has "Read Assets" and "Read Collections" will see all tools listed but will be denied when it tries to run an upload or a bulk update.

Detailed Feature Documentation

MCP Endpoint and Stats

• Purpose: To provide the primary connection string and a snapshot of server capabilities.
• Where to find it: At the top of the page, inside the first grid of cards.
• What you'll see: The full URL for your MCP server and a count of "Read" vs "Write" tools.

How to use it:

1. Locate the MCP Endpoint card.
2. Click the Copy icon (clipboard) next to the URL.
3. If you do not have an API token yet, click the API Management link in the card footer to create one.

Integrations Tab

• Purpose: Step-by-step instructions and configuration files for popular AI platforms.
• Where to find it: The first tab in the main content area.
• What you'll see: Sections for Claude (Claude.ai, Desktop, and Code) and OpenAI (ChatGPT and Responses API).

How to use it:

1. Select the Integrations tab.
2. Find the card corresponding to your AI tool (e.g., Claude Desktop).
3. Use the Copy icon on the code block to copy the JSON configuration.
4. Follow the listed file path (e.g., ~/Library/Application Support/Claude/) to locate where to paste the code on your computer.

Tools Directory

• Purpose: To browse the specific functions available to the AI.
• Where to find it: The Tools tab.
• What you'll see: A grid of cards, each representing a tool. Blue "Eye" icons indicate read-only tools; Amber "Pencil" icons indicate tools that can modify data.

How to use it:

1. Click the Tools tab.
2. Scroll through the list to see tool names (e.g., search_assets) and their descriptions.
3. Use this list to understand exactly what information the AI can access.

Connection Testing

• Purpose: To verify that the MCP server is responding correctly before configuring an AI.
• Where to find it: The Test tab.
• What you'll see: A curl command block and a description of the expected successful response.

How to use it:

1. Click the Test tab.
2. Copy the command from the Test with curl card.
3. Replace YOUR_API_TOKEN with a valid token from your API Management settings.
4. Run the command in your computer's terminal.

Complete Workflows

Workflow: Connect Freedam to Claude Desktop

• Goal: Enable an AI assistant on your computer to search your DAM.
• Prerequisites: Claude Desktop installed; an active API token from Freedam.

Steps:

1. Navigate to the MCP Server page in Administration.
2. Select the Integrations tab.
3. Locate the Claude Desktop card.
4. Click the Copy icon in the code block.
5. Open your file explorer and navigate to the path shown in the card (e.g., %APPDATA%\Claude\ on Windows).
6. Open claude_desktop_config.json in a text editor.
7. Paste the copied configuration into the file and save.
8. Restart Claude Desktop.

• Expected result: A "Freedam" tool icon appears in Claude Desktop, and you can ask it to "List my recent assets."
• If it doesn't work: Ensure you replaced YOUR_API_TOKEN in the config file with your actual token.

Workflow: Verify Tool Permissions

• Goal: Confirm whether the AI can delete or edit assets.
• Prerequisites: Access to the MCP Server admin page.

Steps:

1. Click the Tools tab.
2. Look for the Amber Pencil icon on tool cards.
3. Read the description of any tool with a pencil icon to see if it allows "Update" or "Delete" actions.
4. If only Blue Eye icons are visible, the AI is restricted to viewing data only.

• Expected result: You have a clear understanding of the AI's "write" capabilities.

Tips and Best Practices

• Token Security: Always use a dedicated API token for MCP. If you suspect the token has been compromised, revoke it in API Management to instantly disconnect all AI assistants.
• Read-Only First: When first testing AI integrations, use a token with limited "read" scopes to ensure the AI doesn't accidentally modify assets while you are learning the interface.
• Check the Logs: If an AI says it "can't find any tools," use the Test tab to run a manual curl command. This confirms if the issue is with Freedam or the AI platform's configuration.

Troubleshooting

Issue: AI Assistant cannot connect to the server

• Symptoms: The AI returns an error like "Failed to connect to MCP server" or "401 Unauthorized."
• Cause: The API token is missing, expired, or does not have the correct permissions.
• Fix:
  1. Go to API Management.
  2. Generate a new token.
  3. Update your configuration file (e.g., claude_desktop_config.json) with the new token.
• Prevention: Set tokens to "No Expiry" only if you have strict control over the environment where the AI is running.

Issue: Tools are missing from the AI interface

• Symptoms: The AI connects successfully but says "No tools available."
• Cause: The MCP server is reachable, but the specific tools are not being exposed.
• Fix: Check the Tools tab on the MCP Server page. If the list is empty, contact system support to ensure the MCP plugin is active.
• Prevention: Periodically check the Available Tools count on the overview cards to ensure the number hasn't dropped to zero.

Good to Know

• One endpoint, many AI clients: All AI assistants (Claude Desktop, Claude Code, ChatGPT, etc.) connect to the same Freedam MCP endpoint. Each one simply needs its own API token pasted into the integration snippet.
• AI requests obey the same 60-requests-per-minute limit as any other API token. If an AI gets chatty, it will be throttled just like a normal integration.
• Everything an AI does is audited: every tool call the AI makes shows up in the same audit trail as regular API activity, tagged with the token name, action, IP address, and response. You can review exactly what the AI has been up to in the API Management Overview tab.
• Read-only first is a safe default: issuing the AI a token with only "Read Assets", "Read Collections" and "Read Metadata" is the safest way to let it help with search and discovery without risk of accidental edits or deletions.
• Bulk changes are asynchronous: when the AI triggers a bulk metadata update or an upload, Freedam queues the work and returns an operation ID. The AI can then use the "Get operation status" read-only tool to track progress rather than holding the connection open.