Model Context Protocol

Model Context Protocol (MCP) enables AI models to securely access and interact with your Clear Ideas content. MCP provides a standardized way for AI applications like Claude Desktop to query, retrieve, and modify content while maintaining security and privacy controls.

Overview

MCP allows AI models to access only relevant fragments of your private data, keeping other data encrypted and secure. This privacy-preserving approach ensures that AI models can work with your content without exposing sensitive information unnecessarily.

Key Benefits:

Secure Access: Granular permission controls through scopes
Privacy-Preserving: AI models access only what they need
Standardized Protocol: Compatible with MCP-compliant AI applications
Flexible Authentication: Support for access keys and OIDC (OAuth 2.0)

Prerequisites

Before connecting with MCP, ensure:

Account-Level AI Features: AI features must be enabled at the account level. See AI Settings for configuration.
Site-Level MCP Access: MCP access must be enabled for sites you want to access. See Site AI Settings to enable MCP Access.
Organization Policies: If you're part of an organization, verify that MCP access is permitted. See Organization Settings and Organization Policies Detailed for policy information.

Connecting with MCP

Clear Ideas supports two authentication methods for MCP connections:

Access Key Authentication

Access keys provide programmatic access with specific scopes. This method is ideal for AI applications that need persistent access.

Creating an MCP Access Key:

Navigate to Settings > Access Keys
Click New Access Key
Choose MCP as the key type
Select appropriate scopes:
- mcp:read: Read access (list sites, search content, retrieve documents)
- mcp:write: Write access (create files, save content, create folders)
Set an optional expiration date
Copy the key immediately after creation

Access Key Scopes:

mcp:read: Grants read-only access to:

List accessible sites
Search content across sites
Retrieve document content and context
View file versions and diffs

mcp:write: Grants write access to:

Create new files
Save file content (create new versions)
Create folders

Using Access Keys:

Include the access key in the Authorization header:

Authorization: Bearer YOUR_ACCESS_KEY

For more information about managing access keys, see Access Keys.

OIDC (OAuth 2.0) Authentication

OIDC authentication provides secure, token-based access using OAuth 2.0 standards. This method is ideal for applications that need user consent and token refresh capabilities.

OIDC Configuration:

Register an OIDC Client: Create an OIDC client application in Clear Ideas
Configure Redirect URIs: Specify allowed redirect URIs for your application
Request Scopes: Request appropriate OIDC scopes during authentication
Use Authorization Code Flow: Follow OAuth 2.0 authorization code flow with PKCE

OIDC Scopes:

Standard OIDC scopes are available:

openid: Required for OIDC
profile: User profile information
email: Email address
account: Clear Ideas account information
offline_access: Request refresh tokens

OIDC Access:

OIDC-authenticated users automatically have full MCP access (both read and write) without requiring explicit MCP scopes. The OIDC token provides access based on the user's account permissions.

MCP Endpoint:

The MCP endpoint is available at:

POST https://api.clearideas.com/mcp

The endpoint accepts JSON-RPC 2.0 requests and requires authentication via access key or OIDC token.

Available MCP Tools

Clear Ideas provides a comprehensive set of MCP tools for interacting with content. Tools are organized into read operations (requiring mcp:read scope) and write operations (requiring mcp:write scope).

Read Operations

List Sites

Tool: clearideas.list_sites

List all sites accessible to your account with pagination support.

Parameters:

cursor (optional): Page number for pagination (e.g., "2", "3")
limit (optional): Number of results per page (1-200, default: 50)
accepted (optional): Filter to only accepted site memberships (default: false)

Use Cases:

Discover available sites
Navigate site structure
Filter sites by membership status

List Content

Tool: clearideas.list_content

List content within a site or folder with advanced filtering and sorting options.

Parameters:

siteId (required): ID of the site to list content from
folderId (optional): Parent folder ID (null for site root)
cursor (optional): Page number for pagination
limit (optional): Number of results per page (1-200, default: 100)
includePath (optional): Include ancestor breadcrumb path (default: true)
sort (optional): Sort configuration object with field (name, updatedAt, size) and direction (asc, desc)
updatedSince (optional): ISO date string to filter content updated after timestamp
startsWith (optional): String prefix to filter content names (case-insensitive)
tags (optional): Array of strings to filter content by tags
mimeTypes (optional): Array of MIME types to filter by (only applies to files)

Use Cases:

Browse site structure
Find recently updated files
Filter content by name, tags, or MIME type
Sort content by size or date
List specific file types (e.g., only PDF files)

Search Content

Tool: clearideas.search_content

Search content by name across accessible sites with optional site scoping and filtering.

Parameters:

q (required): Search query (name-based search)
siteIds (optional): Array of site IDs to search within
kind (optional): Filter by content type (file, folder, any, default: any)
searchType (optional): Search algorithm (hybrid, full-text, completion, default: hybrid)
mimeTypes (optional): Array of MIME types to filter by
limit (optional): Maximum results to return (1-200, default: 50)

Use Cases:

Find files by name
Search within specific sites
Filter by file type or MIME type
Use different search algorithms for better results

Retrieve Context

Tool: clearideas.retrieve_context

Retrieve AI-ready context from files using semantic search. Returns relevant content chunks with URLs.

Parameters:

query (required): Search query for semantic context retrieval
siteIds (optional): Array of site IDs to search within
maxChunks (optional): Maximum number of chunks to return (1-200, default: 30)
maxTokens (optional): Token budget for response (500-64000)
mimeTypes (optional): Array of MIME types to filter by

Use Cases:

Get context for AI model prompts
Retrieve relevant information about a topic
Scope searches to specific sites
Control token usage for AI processing

Retrieve Context for File

Tool: clearideas.retrieve_context_for_file

Retrieve extracted text for a specific file with optional version selection and line range extraction.

Parameters:

contentId (required): Content/file ID to retrieve text from
maxTokens (optional): Token budget for response (500-64000)
version (optional): Version number to retrieve (0 for original, higher numbers for newer versions)
versionAsOf (optional): ISO date string to find version active at that time
lines (optional): Line range object with start and end (1-indexed)

Use Cases:

Get full file content
Retrieve specific file versions
Extract specific line ranges
Control token usage for large files

Retrieve Diff for File

Tool: clearideas.retrieve_diff_for_file

Retrieve diff between file versions with optional version selection and line range filtering.

Parameters:

contentId (required): Content/file ID to retrieve diff for
version (optional): Version number to compare (0 for original, higher numbers for newer versions)
priorVersion (optional): Older version number to compare against
versionAsOf (optional): ISO date string to find newer version active at that time
priorVersionAsOf (optional): ISO date string to find older version active at that time
lines (optional): Line range object with start and end (1-indexed)

Use Cases:

Compare file versions
Track changes over time
Review modifications in specific line ranges
Understand version history

Help

Tool: clearideas.help

Show usage guide for Clear Ideas MCP tools.

Parameters: None

Use Cases:

Get tool documentation
Understand available operations
Learn tool usage patterns

Write Operations

Save File

Tool: clearideas.save_file

Save file content to a site. Creates new files when no fileId is provided, or creates new versions when fileId is specified.

Parameters:

siteId (required): ID of the site where the file will be created
folderId (optional): ID of the folder where the file will be created
name (required): Name of the file including extension
content (required): File content as a string
contentType (optional): MIME type (auto-detected from extension if not provided)
fileId (optional): ID of existing file to create a new version

Use Cases:

Create new files
Update existing files (creates new version)
Save files in specific folders
Set explicit MIME types

Note: Requires mcp:write scope and file creation permissions on the target site.

Create Folder

Tool: clearideas.create_folder

Create a new folder in a site.

Parameters:

siteId (required): ID of the site where the folder will be created
folderId (optional): ID of the parent folder (null for site root)
name (required): Name of the folder

Use Cases:

Organize content structure
Create project folders
Build nested folder hierarchies

Note: Requires mcp:write scope and content creation permissions on the target site.

Limitations

Destructive Operations Not Supported

Clear Ideas MCP does not currently support destructive or potentially destructive operations. The following operations are not available via MCP:

File and Folder Deletion: Cannot delete files or folders through MCP tools
Renaming: Cannot rename files or folders through MCP tools
Moving: Cannot move files or folders between locations through MCP tools

These operations are intentionally excluded to prevent accidental data loss and maintain data integrity. To perform these operations, use the Clear Ideas web interface.

Available Write Operations: