Compoid MCP

Compoid MCP Server

Structured long-term memory for AI agents - give any agent a durable, versioned workspace it can search, read from, and write back to across sessions, projects, and even different agents.

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

🧠 Durable Agent Memory

Most agents are amnesiac: every session starts from zero, and whatever context they build up dies with the process. Compoid fixes that. Every account gets a default workspace — its home community (user- ), and the MCP server exposes it as a full read/write surface:

• Project context that survives. An agent working on a project writes decisions, plans, notes, and artifacts into the community; the next session — or a *different* agent — searches, finds, and continues. Memory is structured (records with titles, descriptions, keywords, subjects, resource types, provenance), not a blob of chat history.
• A shared workspace, not a private one. Humans and multiple agents can operate on the same community: your assistant researches, you review the results on compoid.com, it reads your annotations back. One source of truth, versioned and auditable.
• Structured, not a chat log. Records carry typed metadata (20 resource types, rdm:category research-domain classification, up to 5 subjects, creators/keywords/references) and full provenance — who created what, when, and how it changed (updates mint new versions, history preserved).
• Scoped and searchable. Filter by community (a project), by type, by date, by creator, by access level — so "memory" stays queryable at any scale, and restricted communities keep sensitive context (e.g. personal data) out of the public index.

Two natural shapes:

1. Per-project memory — one community per project or initiative; the agent reads state at the start of work and writes back at the end.
2. General workspace — the agent's default community as its standing personal memory: preferences, recipes, plans, references, anything the user asks it to "remember".

Features

This Model Context Protocol (MCP) server provides a secure, remote interface for AI models to interact with Compoid — to search, read, create, update, and delete records and communities, i.e. to *use a Compoid workspace as long-term memory*.

• 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, update existing records (metadata and/or files), or delete published records
• Community Management: Create and update communities with full access control and curation policies
• Collections Management: Search the collection trees of any community and list the records inside each collection
• 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

Full version history: [CHANGELOG.md](CHANGELOG.md)

🚀 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: Install from PyPI

One-line install (published on PyPI, v0.1.7):

pip install compoid-mcp

or run without installing:

uvx compoid-mcp

Then register the local stdio server:

{

"mcpServers": { "Compoid": { "name": "Compoid AI Repository MCP Server", "disabled": false, "type": "stdio", "command": "compoid-mcp", "env": { "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": "Qwen", "COMPOID_UPLOAD_URL": "https://mcps.compoid.com/upload", "UPLOAD_AUTH_TOKEN": "Remote-MCP-Compoid-Pro-Subscription-API-Key" } } } }

## ⚙️ Setup: API Key & Environment Variables

What you need: a Compoid account and a repository API key. Every Compoid account automatically gets a personal API token (named compoid- ); you can also create additional tokens from your Compoid account.

Remote mode — hosted server, no install, no env vars. Point your agent at the hosted endpoint and send your key as a request header (this is Option 1/2 above):

{

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

Local / self-hosted mode — installed from PyPI. The server reads its configuration from environment variables. The only required one is your repository API key; everything else has a working default:

# required

export COMPOID_REPO_API_KEY="your-c…-key"

optional

export COMPOID_AI_API_KEY="your-c…-key" # AI metadata generation export DOWNLOAD_PATH="$HOME/Downloads" # where downloads land export EXTRACT_ARCHIVE="true" # auto-extract downloaded zips export SORT_ORDER="bestmatch" # default search sort

Or set the same variables in the env block of your MCP client config (see Option 4). The full reference — endpoints, AI model, pagination, timeouts, rate limits, logging — is in Configuration → Environment Variables below.

Note: for the hosted mcpv.compoid.com server, per-request headers (X-Compoid-Repo-Key, X-Compoid-AI-Key, Authorization) take precedence over any server-side environment.

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, publications, documents, 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: analysis, image, video, audio, publication, document, software, project, dataset, presentation, workflow, tutorial, other
• 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 (aut