Crates API Documentation

Comprehensive documentation for all MCP tools to manage crates

Overview

The MCPH Crates API provides a comprehensive set of endpoints for working with crates through the Model Context Protocol (MCP). This document covers all available tools for listing, searching, retrieving, uploading, sharing, and managing crates.

All crates tools are accessible through the MCP endpoint at https://mcp.mcph.io/mcp.

API Tools Quick Reference

Fetching Data

crates_list
crates_get
crates_get_download_link
crates_search

Creating & Managing

crates_upload
crates_delete
crates_copy

Sharing Controls

crates_share
crates_unshare

Crates API Tools

crates_list

Lists all crates owned by the authenticated user. Results are paginated and sorted by creation date (newest first).

Input Parameters

limit (optional): Number of crates to return per page. Default: 20, Max: 100.

startAfter (optional): ID of the last crate from the previous page for pagination.

Output

crates: Array of crate metadata objects
lastCrateId: ID of the last crate in the result set (for pagination)
hasMore: Boolean indicating if there are more pages

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crates_list",
    "arguments": { 
      "limit": 5
    }
  }
}

// Response
{
  "crates": [
    {
      "id": "abc123",
      "title": "Example Crate",
      "description": "This is an example crate",
      "category": "markdown",
      "createdAt": "2025-06-24T12:34:56.789Z",
      "mimeType": "text/markdown",
      "size": 1024,
      "tags": ["example", "documentation"],
      "isPublic": true,
      "isPasswordProtected": false
    },
    // ...more crates
  ],
  "lastCrateId": "xyz789",
  "hasMore": true
}

Authentication

Requires authentication. The list only returns crates owned by the authenticated user.

crates_get

Retrieves a crate's contents by its ID. Supports text, images, and binary files. Anonymous uploads are public by default.

Input Parameters

id (required): The unique identifier of the crate.

password (optional): Password for accessing password-protected crates.

Output

content: Array of content objects with:

type: "text" or "image"
text: For text content
data: For image content (base64)
mimeType: For images

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "crates_get",
    "arguments": { 
      "id": "abc123"
    }
  }
}

// Response for Text
{
  "content": [
    {
      "type": "text",
      "text": "# Example Markdown\n\nThis is some sample content."
    }
  ]
}

// Response for Image
{
  "content": [
    {
      "type": "image",
      "data": "base64EncodedImageData...",
      "mimeType": "image/png"
    }
  ]
}

Access Rules

Owner can always access their own crates
Anonymous uploads are public by default
Public crates are accessible by anyone
Password-protected crates require the password parameter
Binary files direct the user to use crates_get_download_link instead

crates_get_download_link

Generates a pre-signed download URL for a crate, especially for binary files or large content. Download links expire by default after 24 hours.

Input Parameters

id (required): The unique identifier of the crate.

expiresInSeconds (optional): Duration in seconds until the download link expires. Default: 86400 (24 hours), Min: 1, Max: 86400.

Output

url: Pre-signed URL for downloading the crate
validForSeconds: Number of seconds the URL will be valid
expiresAt: ISO timestamp when the URL expires

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "crates_get_download_link",
    "arguments": { 
      "id": "abc123",
      "expiresInSeconds": 3600
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Download link for crate Example File: https://storage.example.com/signed-url-abc123\nThis link is valid for 1 hours and 0 minutes."
    }
  ],
  "url": "https://storage.example.com/signed-url-abc123",
  "validForSeconds": 3600,
  "expiresAt": "2025-06-24T13:34:56.789Z"
}

Access Rules

Same as crates_get: owner can always access, anonymous uploads are public by default, and access to shared crates follows the same permission rules.

crates_search

Searches for crates by query text. The search covers title, description, tags, and metadata fields.

Input Parameters

query (required): Text to search for in crates.

Output

crates: Array of matching crate metadata objects (same structure as in crates_list).

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "crates_search",
    "arguments": { 
      "query": "example"
    }
  }
}

// Response
{
  "crates": [
    {
      "id": "abc123",
      "title": "Example Crate",
      "description": "This is an example crate",
      "category": "markdown",
      "createdAt": "2025-06-24T12:34:56.789Z",
      "mimeType": "text/markdown",
      "size": 1024,
      "tags": ["example", "documentation"],
      "isPublic": true,
      "isPasswordProtected": false
    },
    // ...more matching crates
  ]
}

Authentication

Requires authentication. Search only returns crates owned by the authenticated user.

crates_upload

Uploads a new crate. Small text content is uploaded directly; large/binary files return a pre-signed URL that must be used to upload the file separately.

Input Parameters

fileName (required): Original filename of the content being uploaded.

contentType (required): MIME type of the content (e.g., "text/markdown", "image/png").

data (required for direct upload): The content to upload as a string. Required for text content.

title (optional): A title for the crate. Defaults to fileName if not provided.

description (optional): Description of the crate.

category (optional): Category of the crate ("markdown", "code", "image", "json", "binary").

tags (optional): Array of string tags to associate with the crate.

metadata (optional): Object with additional metadata key-value pairs.

isPublic (optional): Boolean indicating if the crate should be public. Anonymous uploads are public by default.

password (optional): Password to protect the crate.

Output for Direct Upload

crate: Object containing the created crate metadata

Output for Pre-signed URL (binary/large files)

uploadUrl: Pre-signed URL to upload the file content
crateId: ID of the crate that will be created
gcsPath: Google Cloud Storage path where the file will be stored

Example - Text Upload

// Request
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "crates_upload",
    "arguments": { 
      "fileName": "notes.md",
      "contentType": "text/markdown",
      "data": "# Meeting Notes\n\n- Point 1\n- Point 2",
      "title": "Important Meeting Notes",
      "description": "Notes from our team meeting",
      "tags": ["meeting", "team", "notes"],
      "isPublic": true
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Crate uploaded successfully. Crate ID: def456"
    }
  ],
  "crate": {
    "id": "def456",
    "title": "Important Meeting Notes",
    "description": "Notes from our team meeting",
    "category": "markdown",
    "createdAt": "2025-06-24T12:34:56.789Z",
    "fileName": "notes.md",
    "size": 42,
    "tags": ["meeting", "team", "notes"],
    "ownerId": "user123",
    "shared": {
      "public": true
    }
  }
}

Example - Binary Upload

// Request
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "crates_upload",
    "arguments": { 
      "fileName": "data.bin",
      "contentType": "application/octet-stream",
      "title": "Binary Data File",
      "category": "binary"
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Upload your file using this URL with a PUT request: https://storage.example.com/upload-url-def456. Crate ID: def456"
    }
  ],
  "uploadUrl": "https://storage.example.com/upload-url-def456",
  "crateId": "def456",
  "gcsPath": "crates/def456/data.bin"
}

Authentication

Requires authentication for non-anonymous uploads. Anonymous uploads are created with ownerId="anonymous" and are public by default.

crates_share

Updates a crate's sharing settings, allowing you to make it public or password-protected.

Input Parameters

id (required): The unique identifier of the crate to share.

password (optional): Password to protect the crate. If not provided, the crate will be made public without password protection.

Output

id: ID of the shared crate
shareUrl: Full URL to access the crate
crateLink: Shortened URL (domain and path)

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "crates_share",
    "arguments": { 
      "id": "def456",
      "password": "secret123"
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Crate def456 sharing settings updated. Link: https://mcph.io/crate/def456"
    }
  ],
  "id": "def456",
  "shareUrl": "https://mcph.io/crate/def456",
  "crateLink": "mcph.io/crate/def456"
}

Authentication

Requires authentication. Only the owner can change a crate's sharing settings.

crates_unshare

Makes a crate private by removing all sharing settings (public access and password protection).

Input Parameters

id (required): The unique identifier of the crate to make private.

Output

id: ID of the crate that was made private

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "crates_unshare",
    "arguments": { 
      "id": "def456"
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Crate def456 has been unshared. It is now private."
    }
  ],
  "id": "def456"
}

Authentication

Requires authentication. Only the owner can make a crate private.

crates_delete

Permanently deletes a crate's data and metadata. This action requires confirmation and cannot be undone.

Input Parameters

id (required): The unique identifier of the crate to delete.

Confirmation Process

This tool requires explicit confirmation through the MCP elicitation process. The caller will be prompted to confirm the deletion and can provide an optional reason.

Output

id: ID of the deleted crate

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "crates_delete",
    "arguments": { 
      "id": "def456"
    }
  }
}

// Response after confirmation
{
  "content": [
    {
      "type": "text",
      "text": "Crate def456 has been successfully deleted."
    }
  ],
  "id": "def456"
}

Authentication

Requires authentication. Only the owner can delete a crate.

crates_copy

Copies an existing crate to the user's collection. If the crate is already owned by the user, it will not be copied. The new copy will be private by default.

Input Parameters

id (required): The unique identifier of the crate to copy.

Output

crate: The new crate object with complete metadata

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "crates_copy",
    "arguments": { 
      "id": "abc123"
    }
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "Crate copied successfully to your collection. New crate ID: def456"
    }
  ],
  "crate": {
    "id": "def456",
    "title": "Copy of Example Crate",
    "description": "This is an example crate",
    "category": "markdown",
    "createdAt": "2025-06-24T12:34:56.789Z",
    "mimeType": "text/markdown",
    "size": 1024,
    "tags": ["example", "documentation"],
    "isPublic": false,
    "isPasswordProtected": false
  }
}

Authentication

Requires authentication. Anonymous users cannot copy crates.

Access Rules

Users can only copy crates that are public or owned by anonymous users. Private crates cannot be copied unless the user is the owner, in which case copying is not needed as they already own the crate.

Important Notes

Anonymous Uploads: All anonymously uploaded crates are public by default. These are automatically created with ownerId="anonymous" and public=true.
Authentication: Use API keys for authenticated access to your own crates. API keys should be passed as Bearer tokens in the Authorization header.
Binary Files: For binary files, use crates_get_download_link instead of crates_get. When uploading binary files, you'll receive a pre-signed URL to upload the content separately.
Retention: Crates are automatically deleted after 30 days. Download links expire after 24 hours by default.
Error Handling: All tools return clear error messages when operations fail. Common errors include permission issues, invalid IDs, and missing required parameters.

← Back to Documentation