--- title: Model Context Protocol description: >- Connect AI models to Clear Ideas using Model Context Protocol (MCP). Learn how to configure access keys, OIDC authentication, and use available MCP tools for secure AI integration. ogTitle: Model Context Protocol Guide ogDescription: >- Master Model Context Protocol integration with Clear Ideas. Configure access keys, OIDC authentication, and use MCP tools for secure AI access ogImage: /assets/images/og/guide-model-context-protocol.webp navigation: icon: fasl fa-diagram-project --- # 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) - **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](/ai/ai-settings) for configuration. 2. **Site-Level MCP Access**: MCP access must be enabled for sites you want to access. See [Site AI Settings](/site-administrator-guide/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](/organizations/organization-settings) and [Organization Policies Detailed](/organizations/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](/security/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](/security/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 ## Related Documentation - [Access Keys](/security/access-keys) - Create and manage MCP access keys - [AI Settings](/ai/ai-settings) - Configure account-level AI features - [Site AI Settings](/site-administrator-guide/site-ai-settings) - Enable MCP access at site level - [Organization Settings](/organizations/organization-settings) - Organization-level MCP configuration - [Organization Policies Detailed](/organizations/organization-policies-detailed) - Understanding MCP policy controls