Documentation

Model Context Protocol

View as Markdown

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)
  • Governed Evidence: Content reads and cited answers can be exported from Governance Activity when governance is active

Prerequisites

Before connecting with MCP, ensure:

  1. Account-Level AI Features: AI features must be enabled at the account level. See AI Settings for configuration.
  2. Site-Level MCP Access: MCP access must be enabled for sites you want to access. See Site AI Settings to enable MCP Access.
  3. 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:

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

Access Key Scopes:

mcp:read: Grants read-only access to:

  • List accessible sites
  • Inspect site metadata and content metadata
  • List recent content and file version metadata
  • 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:

  1. Register an OIDC Client: Create an OIDC client application in Clear Ideas
  2. Configure Redirect URIs: Specify allowed redirect URIs for your application
  3. Request Scopes: Request appropriate OIDC scopes during authentication
  4. 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.

Clear Ideas runs MCP over stateless HTTP transport for reliability across production web workers. If an MCP client sends an explicit Mcp-Session-Id, Clear Ideas uses that value to correlate governed MCP evidence. If the client does not send one, each request is handled independently.

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. Results include relationship (owner or shared), current role, tags, read-only state, content permissions, active file and folder counts, and update timestamps.

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
  • Check whether a site is owned by the current user or shared with them
  • Check whether the current user can upload, create folders, edit content, or delete content

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)
  • See content tags, paths, extraction status, summary status, and version counts without retrieving file text

Get Site Metadata

Tool: clearideas.get_site_metadata

Get metadata for one accessible site without listing its contents.

Parameters:

  • siteId (required): ID of the site to inspect

Returns:

  • Relationship: owner or shared
  • Current user role
  • Read-only state
  • Site tags
  • Content permissions for read, list, search, upload, create folder, edit, and delete
  • Active file and folder counts
  • Updated timestamp

Use Cases:

  • Decide whether content can be uploaded or edited in a site
  • Check whether a site is read-only
  • Inspect ownership/shared relationship and role
  • Get site tags and counts before browsing

Get Content Metadata

Tool: clearideas.get_content_metadata

Get metadata for one file or folder without retrieving file text.

Parameters:

  • contentId (required): ID of the file or folder to inspect

Returns:

  • Name, kind, site, parent, and path
  • Tags, content type, size, and extension
  • Extraction status and summary status
  • Current version and version count
  • Created and updated timestamps
  • Authenticated URL

Use Cases:

  • Inspect a file before retrieving full text
  • Check whether a summary or extracted text is available
  • Find tags, path, timestamps, and version count
  • Avoid retrieving large content when metadata is enough

List Content Versions

Tool: clearideas.list_content_versions

List available version metadata for a file without retrieving version text.

Parameters:

  • contentId (required): ID of the file to inspect versions for

Use Cases:

  • See what versions are available before retrieving historical content
  • Choose versions to compare with clearideas.retrieve_diff_for_file
  • Inspect version timestamps, sizes, content types, and extensions

List Recent Content

Tool: clearideas.list_recent_content

List recently updated accessible files and folders across one or more sites. Results are sorted by newest update first.

Parameters:

  • siteIds (optional): Array of site IDs to scope recent content
  • kind (optional): Filter by content type (file, folder, or any, default: any)
  • mimeTypes (optional): Array of MIME types to filter by
  • tags (optional): Array of tags to filter by
  • updatedSince (optional): ISO timestamp to only return content updated since that time
  • limit (optional): Maximum number of items to return (1-200, default: 50)

Use Cases:

  • Answer "latest", "recent", or "recently changed" content requests
  • Review recently updated files across accessible sites
  • Filter recent updates by site, tag, type, or MIME type

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

Governance Note: The site lookup is ordinary audit context. Returned content chunks are treated as content access and can create governed MCP evidence when governance is active.

Retrieve Context for File

Tool: clearideas.retrieve_file_content

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-32000, default: 12000)
  • 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
  • Page through large files using returned line paging metadata
  • Control token usage for large files

Governance Note: File content reads can create governed MCP evidence. Evidence records include content identity, version, line range or paging metadata, text length, and hashes rather than needing to duplicate full raw file text in every export.

Retrieve File Summary

Tool: clearideas.retrieve_file_summary

Retrieve the full AI-generated summary for a specific file when one is available. If the file does not have a completed summary, the tool returns a status message instead.

Parameters:

  • contentId (required): Content/file ID to retrieve the AI summary from

Use Cases:

  • Get a concise overview before retrieving full file content
  • Use an existing file summary in prompts or workflows
  • Check whether a file has a completed AI summary

Governance Note: Summary reads can create governed MCP evidence only when a completed summary is returned. Summary evidence references the content version and summary artifact metadata when available.

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, upload permissions on the target site, and a site that is not read-only.

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, folder creation permissions on the target site, and a site that is not read-only.

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:

  • Creating new files (clearideas.save_file without fileId)
  • Creating new file versions (clearideas.save_file with fileId)
  • Creating folders (clearideas.create_folder)

OpenAI MCP Specification Tools

Clear Ideas also provides tools that comply with the OpenAI MCP specification for compatibility with OpenAI-compatible MCP clients.

Search (OpenAI MCP)

Tool: search

Search content across accessible sites (OpenAI MCP specification compliant).

Parameters:

  • query (required): Search query string

Use Cases:

  • Simple content search
  • OpenAI MCP client compatibility

Fetch Document (OpenAI MCP)

Tool: fetch

Fetch the full contents of a document by its unique identifier (OpenAI MCP specification compliant).

Parameters:

  • id (required): Document/content ID

Use Cases:

  • Retrieve a bounded document preview
  • OpenAI MCP client compatibility
  • Use clearideas.retrieve_file_content with lines and/or maxTokens when a file is truncated or you need controlled larger reads

Cited Answers

Answer with Citations

Tool: clearideas.answer_with_citations

Generate a cited answer from accessible Clear Ideas content. This tool behaves more like AI Chat than a simple data-access tool because it produces an assistant answer grounded in retrieved sources.

Governance Note: When governance is active, answer-with-citations evidence can include the user question, assistant answer, citations, referenced content ids, grounding metadata, web-search state, model metadata when available, and linked source access events.

MCP Evidence and Audit Trail

MCP activity appears in the audit trail with MCP correlation metadata. Governed MCP evidence is created only for activity that gives substantive information to AI context or produces a cited AI answer.

Governed evidence examples:

  • clearideas.retrieve_context returned content chunks
  • clearideas.retrieve_file_content file text reads
  • clearideas.retrieve_file_summary completed summary reads
  • clearideas.answer_with_citations cited AI answers
  • OpenAI-compatible fetch content previews

Audit-only examples:

  • clearideas.list_sites
  • clearideas.list_content
  • clearideas.search_content
  • OpenAI-compatible search
  • clearideas.save_file
  • clearideas.create_folder

Organization administrators review MCP-linked activity and export available evidence from Audit & Governance > Governance Activity. Evidence exports are grouped by explicit evidence correlation, not by timing or heuristic client behavior.

Security Considerations

Scope-Based Access Control

MCP uses granular scopes to control access:

  • Read Operations: Require mcp:read scope
  • Write Operations: Require mcp:write scope
  • OIDC Users: Automatically have full access (read and write)

Site-Level Permissions

Even with appropriate MCP scopes, operations are limited by:

  • Site membership and permissions
  • Site-level MCP access settings
  • Organization policies
  • Site read-only state for write operations

Access Key Security

  • Store access keys securely
  • Rotate keys regularly
  • Use minimal required scopes
  • Set expiration dates when possible
  • Revoke compromised keys immediately

For more information, see Access Keys.

Best Practices

Scope Selection

Principle of Least Privilege: Grant only the minimum scopes needed:

  • Use mcp:read for read-only operations
  • Add mcp:write only when write access is required
  • Avoid granting write access unnecessarily

Error Handling

MCP tools return structured error responses:

  • Check for scope errors when operations fail
  • Verify site permissions before operations
  • Handle rate limiting appropriately

Performance Optimization

  • Use pagination (cursor and limit) for large result sets
  • Treat fetch as a bounded document preview; large payloads are truncated around 64 KB
  • Set appropriate maxTokens limits for context retrieval
  • Use clearideas.retrieve_file_content with maxTokens or line ranges when you need controlled access to larger files; its response includes line paging metadata so callers can request the next range
  • Use siteIds to scope searches when possible
  • Leverage filtering options to reduce result sets

Version Management

  • Use version parameters to access historical content
  • Compare versions using diff tools
  • Track changes over time with version history