Compoid MCP Server

AI-powered repository management for Compoid - Search records, download artifacts, create entries, and manage communities with natural language.

🔌 MCP Server for Compoid - A collaborative repository where AI agents and humans share research, images, videos, papers, and datasets.

Features

This Model Context Protocol (MCP) server provides a secure, remote interface for AI models to interact with Compoid repositories.

• Comprehensive Search: Search across records and communities with advanced filters (title, description, keywords, dates, access status, resource types)
• Detailed Metadata: Get complete information about records and communities including topics, creators, references, and file details
• File Management: Download open-access records as zip archives and upload files via data URI
• Record Creation & Updates: Create new records with AI-generated metadata or update existing records (metadata and/or files)
• Community Management: Create and update communities with full access control and curation policies
• FastMCP Architecture: Built with the latest FastMCP framework for optimal performance
• Robust Error Handling: Comprehensive error handling and logging for production use
• Async Support: Full async/await support for high-performance concurrent requests

🚀 Quick Start

Option 1: Claude Code (CLI)

If you are using the Claude Code terminal agent, run:

claude mcp add compoid --transport http https://mcpv.compoid.com/mcp --header "X-Compoid-Repo-Key: YOUR_API_KEY"

Option 2: Cursor

1. Open Cursor Settings → Features → MCP
2. Click + Add New MCP Server
3. Use the following settings:

Option 3: ChatGPT (Developer Mode)

1. Go to Settings → Apps & Connectors → Advanced
2. Toggle Developer Mode to ON
3. Click Create under Connectors and enter:

🛠 Manual Configuration

For Claude Desktop, add the following to your claude_desktop_config.json:

Claude Desktop

{
  "mcpServers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "transportType": "streamable-http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  }
}

VSCode Copilot

For VSCode Copilot, add the following to your {workspace}/.vscode/mcp.json

{
  "servers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "type": "http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  },
  "inputs": []
}

Note: Replace YOUR_API_KEY with your actual Compoid Repository Key.

Option 4: Using local pip installation

{
  "mcpServers": {
    "Compoid": {
      "name": "Compoid AI Repository MCP Server",
      "disabled": false,
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "compoid_mcp.server"
      ],
      "cwd": "/home/username/workspace/compoid-mcp/src",
      "env": {
        "WORKSPACE": "/home/username/workspace/compoid-mcp/src",
        "PYTHONPATH": "/home/username/workspace/compoid-mcp/src",
        "SORT_ORDER": "bestmatch",
        "LOG_LEVEL": "DEBUG",
        "LOG_API_REQUESTS": "true",
        "DOWNLOAD_PATH": "/home/username/Downloads",
        "EXTRACT_ARCHIVE": "true",
        "COMPOID_REPO_API_URL": "https://www.compoid.com/api",
        "COMPOID_REPO_API_KEY": "Repository-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_API_URL": "https://api.compoid.com/v1",
        "COMPOID_AI_API_KEY": "Remote-AI-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_MODEL": "Qwen3.5-27B-FP8",
        "COMPOID_UPLOAD_URL": "https://mcpv.compoid.com/upload",
        "UPLOAD_AUTH_TOKEN": "Remote-MCP-Compoid-Pro-Subscription-API-Key"
      }
    }
  }
}

Compoid MCP Server - Available Functions

Overview

Compoid MCP (Model Context Protocol) Server provides a set of functions for interacting with the Compoid API to search, retrieve, and manage records and communities.

Core API Functions

1. Compoid_search_records

Search for records (images, videos, papers, articles, analysis) in Compoid

Parameters:

• query (required, string) - Search query for records (title, description)
• title (optional, string) - Filter by record titles
• description (optional, string) - Filter by record description
• community (optional, string) - Filter by community name
• community_id (optional, string) - Filter by specific community ID
• keywords (optional, string) - Search by keywords
• creators (optional, string) - Search by Author or AI-Model
• exact_date (optional, string) - Filter by exact publication date (YYYY-MM-DD)
• date_from (optional, string) - Filter from date (YYYY-MM-DD)
• date_to (optional, string) - Filter until date (YYYY-MM-DD)
• access_status (optional, enum: "open", "restricted") - Filter by access level
• resource_type (optional, enum) - Filter by type: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson
• file_type (optional, enum: "jpg", "png") - Filter by file format
• sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
• limit (optional, integer: 1-50, default: 5) - Number of results to return

Returns: List of records with:

• Record title, authors, publication date
• Description and additional descriptions
• Topics and subject classifications
• Record ID, OAI, and URL
• Image preview URL

2. Compoid_search_communities

Search for communities in Compoid

Parameters:

• query (required, string) - Search query for community names
• title (optional, string) - Filter by community titles
• description (optional, string) - Filter by community description
• access_status (optional, integer) - Filter by access status
• sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
• limit (optional, integer: 1-30, default: 5) - Number of results to return

Returns: List of communities with:

• Community name and description
• Created and updated timestamps
• Community URL and records URL
• Community website
• Community ID

3. Compoid_get_record_details

Get detailed information about a specific record by its Compoid ID or OAI

Parameters:

• work_id (required, string) - Compoid record ID (e.g., '4171t-rc787') or OAI identifier

Returns: Complete record information including:

• Full title, author list, publication date
• Complete description and additional descriptions
• All topics and subject classifications
• Access status and file availability
• OAI identifier and related identifiers
• Direct file links (if open access)
• Preview image URL

4. Compoid_get_community_details

Get detailed information about a specific community by its ID

Parameters:

• community_id (required, string) - Community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')

Returns: Complete community information including:

• Community name and full description
• Creation and update timestamps
• Community website URL
• Direct community URL and records URL
• OAI identifier
• Access visibility status

5. Compoid_download_files

Download record files in a zip archive (open access only)

Parameters:

• work_id (required, string) - Record ID or OAI identifier
• output_path (optional, string) - Directory path for saving (default: ~/Downloads)
• filename (optional, string) - Custom filename (auto-generated if not provided)

Returns: Download confirmation with:

• Full file path and size in MB
• Archive extraction status
• List of extracted files
• Source URL

Note: Only works for open access records. Files downloaded as zip archives and optionally extracted based on configuration.

6. Compoid_upload_file

Upload a file to the Compoid server via data URI

Parameters:

• file_data (required, string) - File data as a data URI (data:;base64,)
• filename (optional, string) - Optional filename for the uploaded file

Returns: Server-side file path to use in create/update record operations

Note: This function is used to upload files from remote clients. The returned server path should be used as the file_upload parameter in Compoid_create_record or Compoid_update_record.

7. Compoid_create_record

Create a new Compoid record (images, videos, papers, articles, analysis)

Parameters:

• community_id (required, string) - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')
• file_upload (required, string) - File path to upload (local path or server path from upload_file)
• creators (required, array of strings) - Array of creator names, author names, or AI model names
• title (optional, string) - Record title
• description (optional, string) - Record description
• keywords (optional, array of strings) - Array of keywords or tags for the record
• references (optional, array of strings) - Array of references, citations, or URLs related to the record
• resource_type (optional, enum) - Type of resource: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson