@cplace/mcp-server

An MCP (Model Context Protocol) server that provides Claude Desktop and Claude Code with tools to interact with cplace APIs. This server exposes cplace functionality through a comprehensive set of MCP tools for workspace management, page operations, search capabilities, layout management, type definitions, automation scripts, and version history tracking.

The server supports a profile-based tool loading system to optimize LLM context usage by only loading the tools you need.

Installation & Setup

Remote MCP Server (Recommended)

A hosted MCP server is available at mcp.cplace.com. This is the recommended operation model — no local installation required, always up-to-date, and all profiles are available.

Claude Code

claude mcp add --transport http cplace https://mcp.cplace.com --header "cplace-url: https://${CPLACE_PROJECT_API_TOKEN}@base.cplace.io"

Claude Desktop

{
   "mcpServers": {
      "cplace": {
         "command": "/npx",
         "args": [
            "--ignore-existing",
            "-y",
            "@cplace/mcp-server@latest"
         ],
         "env": {
            "CPLACE_URL": "https://base.cplace.io/",
            "API_TOKEN": "****"
         }
      }
   }
}

Local Installation (Alternative)

If you prefer to run the MCP server locally (e.g., for development or air-gapped environments), you can install it via npx.

Claude Desktop

By default, only the core tools are loaded. Add this entry to your Claude Desktop MCP server configuration file:

Option 1: Separate credentials (traditional)

{
   "mcpServers": {
      "cplace": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/mcp-server@latest"],
         "env": {
            "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
            "API_TOKEN": "your-api-token"
         }
      }
   }
}

Option 2: URL-embedded credentials

{
   "mcpServers": {
      "cplace": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/mcp-server@latest"],
         "env": {
            "CPLACE_URL": "https://[email protected]/your-tenant"
         }
      }
   }
}

Claude Code

Claude Code has built-in Tool Search that defers tool loading until needed, so there is no context window penalty for loading all profiles. The recommendation for Claude Code is to use --profiles=all.

Option 1: Separate credentials

claude mcp add cplace \
  --env CPLACE_URL=https://your-cplace-instance.com/your-tenant \
  --env API_TOKEN=your-api-token \
  -- npx --ignore-existing -y @cplace/mcp-server@latest --profiles=all

Option 2: URL-embedded credentials

claude mcp add cplace \
  --env CPLACE_URL=https://[email protected]/your-tenant \
  -- npx --ignore-existing -y @cplace/mcp-server@latest --profiles=all

Verify the installation:

claude mcp list

Why All Profiles Are Recommended for Claude Code

Claude Code has a built-in Tool Search feature that defers tool loading — tool definitions are only loaded into the context window when actually needed. This means there is no context window penalty for registering all profiles upfront.

Benefits:

• Up to 85% reduction in token usage from tool definitions compared to loading them all upfront
• Improved accuracy in tool selection (less noise from unused tools)
• Full access to all tools without manual profile management

Check the Effect: Run /context in Claude Code to see your current token usage breakdown.

Note: This applies to Claude Code specifically. Other MCP clients that load all tool definitions upfront may benefit from using selective profiles instead. See the Profile System section for details.

Installing a Specific Version

By default, npx installs the latest version of the MCP server. To install a specific version, add the version number to the package name:

@cplace/[email protected]

instead of

@cplace/mcp-server@latest

Replace 0.1.15 with your desired version number. You can find available versions on npm.

Authentication Notes

The installation examples above show two authentication approaches:

• Separate credentials: Traditional CPLACE_URL + API_TOKEN approach
• URL-embedded credentials: Token embedded in the URL like https://[email protected]/tenant

Priority: If both API_TOKEN and URL-embedded credentials are provided, API_TOKEN takes precedence. This ensures backwards compatibility and allows secure credential override.

cplace Requirements

The cplace-mcp-endpoints repository must be part of the deployment. These plugins must be activated in the application.properties:

• cf.cplace.mcpEndpoints - provides the MCP API endpoints
• cf.cplace.apiToken - required for authentication

Additional Configuration Properties

The following configuration properties must be set for API Token authentication to work:

• cplace.plugins.cf.cplace.apiToken.enable=true - Hidden property that actually enables API Token authentication (not documented in ops configuration reference, see issue #750)
• cplace.plugins.cf.cplace.apiToken.headerName=X-Cplace-Api-Token - HTTP header name for the API token (default value, should not be changed)

Usage

1. Obtain an API Token for your cplace system (see cplace documentation)
   • Navigate to your user profile in cplace
   • Click on "Action" -> "View my API Tokens"
   • Create a new API Token
   • Copy the token value
2. Configure your credentials (see Installation section above)
3. If Claude Desktop is running, close it
4. Add the MCP server configuration to Claude Desktop
5. Open Claude Desktop - the cplace tools should now be available

Version Compatibility

The MCP server and cplace backend must be synchronized to work correctly. Version mismatches can occur when either component is upgraded independently.

Checking Version Compatibility

Ask Claude to check version compatibility:

Check the version compatibility between the MCP server and the cplace backend

Claude will internally use the cplace_check_version_compatibility tool to perform the check.

Understanding the Results

Claude will report one of these outcomes:

✅ Compatible

Your MCP server package version matches what the backend expects. Everything is working correctly, and no action is needed.

⚠️ Version Mismatch

The versions don't match. There are two possible scenarios:

Scenario 1: MCP Server Newer Than Backend

⚠️ Version Mismatch Detected

Your MCP server package is newer than what the cplace backend currently supports:

- Your MCP server package version: 1.0.5
- Backend expects version: 1.0.2

What This Means: The cplace backend hasn't been upgraded yet to support features in your MCP server package version. This could lead to unexpected behavior or errors when using certain tools.

Resolution Options:

Option A: Downgrade MCP Server (Recommended for Local Installations)

If you're using a local MCP server installation, you can downgrade to match the backend version. Follow the instructions in the Installing a Specific Version section above to install version 1.0.2 (the version your backend expects).

Example for Claude Desktop:

{
   "mcpServers": {
      "cplace": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/[email protected]"],
         "env": {
            "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
            "API_TOKEN": "your-api-token"
         }
      }
   }
}

After updating the configuration, close and reopen Claude Desktop, then run the version check again to confirm compatibility.

Option B: Upgrade Backend

Contact your cplace administrator to upgrade the backend deployment to the latest version.

Scenario 2: Backend Newer Than MCP Server

⚠️ Version Mismatch Detected

Your cplace backend has been upgraded and now expects a newer package version:

- Your MCP server package version: 1.0.2
- Backend expects version: 1.0.5

What This Means: The backend has been upgraded with new features that require a newer MCP server package version.

Resolution:

The MCP server will automatically upgrade to the latest version on the next restart when using @latest. If you're using a version-pinned installation (e.g., @1.0.2), update your configuration to either specify the new version or use @latest to always fetch the newest version:

Example for Claude Desktop (auto-upgrade to latest):

{
   "mcpServers": {
      "cplace": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/mcp-server@latest"],
         "env": {
            "CPLACE_URL": "https://your-cplace-instance.com/your-tenant",
            "API_TOKEN": "your-api-token"
         }
      }
   }
}

Close and reopen Claude Desktop to apply the changes, then run the version check again to confirm compatibility.

Changing the cplace System

There are two approaches for working with multiple cplace systems:

Option A: Edit and restart Update the CPLACE_URL and/or API_TOKEN values in the Claude Desktop configuration, then close & reopen Claude Desktop.

Option B: Multiple labeled entries (recommended for frequent switching) Define a separate entry per system under mcpServers, each with a distinct key (e.g., cplace-dev, cplace-prod). Disable unused entries by removing them or commenting them out — Claude Desktop does not support disabling entries without removing them from the config.

{
   "mcpServers": {
      "cplace-dev": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/mcp-server@latest"],
         "env": {
            "CPLACE_URL": "https://dev.cplace.io/tenant",
            "API_TOKEN": "dev-token"
         }
      },
      "cplace-prod": {
         "command": "npx",
         "args": ["--ignore-existing", "-y", "@cplace/mcp-server@latest"],
         "env": {
            "CPLACE_URL": "https://prod.cplace.io/tenant",
            "API_TOKEN": "prod-token"
         }
      }
   }
}

Keep only the entry for the system you are currently working with active. Remove or comment out the others to avoid loading unused tools into Claude's context.

Profile System

The MCP server uses a profile-based tool loading system to optimize LLM context usage. By default, only the core profile is loaded if no profiles are specified, providing essential operations while keeping context usage low. You can load additional tool groups by specifying profiles via CLI arguments or by using the cplace_manage_profiles tool.

Available Tool Profiles

| Profile | Description | |---------|-------------| | core | Essential operations including CSV export | | workspace-admin | Workspace creation and app management | | history | Version history | | layouts | Widget and layout management | | resource-management | Resource planner widget configuration | | types-write | Type and attribute management | | low-code | Validators, change listeners, workflows, script execution, job scripts | | jobs | Job monitoring and management | | project-planning | Schedule analysis and PowerPoint export | | solution-management | Solution package management and inspection | | application-settings | Tenant-wide application settings and theming |

Profile Usage Examples

# Default - core functionality only
npx --ignore-existing -y @cplace/mcp-server@latest

# Dashboard development (core + layouts)
npx --ignore-existing -y @cplace/mcp-server@latest --profiles=layouts

# Type development (core + types-write + low-code)
npx --ignore-existing -y @cplace/mcp-server@latest --profiles=types-write+low-code

# Load all available profiles
npx --ignore-existing -y @cplace/mcp-server@latest --profiles=all

Dynamic Profile Management

You can ask Claude to manage profiles at runtime using natural language. Claude will use the cplace_manage_profiles tool to handle your requests:

Example messages:

• "What profiles are currently active?"
• "Show me all available profiles"
• "Activate all profiles"
• "Switch to the layouts and types-write profiles"

Note: Profile changes are saved to ~/.cplace-mcp-profiles.json but require a server reconnect to take effect. The MCP server loads tools once at startup and cannot dynamically register/unregister tools during runtime.

To reconnect in Claude Code: Use the /mcp command, then select the cplace MCP server and click Reconnect. To reconnect in Claude Desktop: Close and reopen the application.

Profile Resolution Priority

The server uses a three-tier priority system to determine which profiles are active at startup:

1. Stored Preferences (Highest Priority): Profiles saved via cplace_manage_profiles tool, stored in ~/.cplace-mcp-profiles.json. These are path-specific (keyed by working directory), user-specific (API token hash), and tenant-specific (URL).

2. CLI Argument (Medium Priority): The --profiles= argument in your MCP server configuration. Used when no stored preference exists for the current directory/user/tenant combination.

3. Code Default (Lowest Priority): Falls back to the "core" profile only when neither stored preferences nor CLI arguments are provided.

Special Rules:

• The "core" profile is always included automatically, regardless of configuration
• Profile preferences are directory-specific: /project-a can have different profiles than /project-b for the same user
• The cplace_manage_profiles tool is always available

Available Profiles and Tools

Always Available (No Profile Required)

These tools are always registered regardless of which profiles are active.

Utilities:

• cplace_get_icon_names - Get all available icon names in the cplace system (FontAwesome, cplace custom, HUI utility icons)
• cplace_check_version_compatibility - Check version compatibility between the MCP server and the cplace backend API

Apps Catalog:

• cplace_list_apps_catalog - List all apps in the cplace apps catalog with their overview, dependencies, and investigation status
• cplace_get_app_details - Get detailed documentation for a specific cplace app including types, attributes, widgets, and dependencies

Profile Management:

• cplace_manage_profiles - Dynamically manage active profiles

Core (Always Loaded)

Essential operations including workspace navigation, page CRUD operations, search, users, documents, and references.

Workspace Management:

• cplace_list_workspaces - Get all workspaces with essential properties
• cplace_get_workspace_details - Get comprehensive details about a specific workspace including all metadata, permissions, type definitions, styling, and configuration
• cplace_list_types - List all types available in a workspace
• cplace_get_type_datamodel - Get the datamodel of a type including its attributes, constraints, and permissions

Page Operations:

• cplace_get_by_uid - Get entity (page or person) by UID with full details
• cplace_manage_page - Create or update a page with attributes and content
• cplace_delete_page - Permanently delete a single page (leaf pages only)
• cplace_delete_page_with_children - Permanently delete a page and optionally all its children
• cplace_copy_page - Copy a page with optional children to a new location
• cplace_edit_page_content - Edit page wiki content using str_replace for surgical text replacements without reproducing the entire content

Search:

• cplace_search_pages - Search pages of a type in cplace with advanced filtering
• cplace_search_pages_fulltext - Make a fulltext search across all pages in cplace
• cplace_list_pages_of_type - List all pages of a specific type in a workspace
• cplace_search_pages_csv - Export search results to CSV format

Users & References:

• cplace_get_person_by_name - Get details about a person by searching for their name
• cplace_get_current_user - Get information about the currently logged-in user
• cplace_get_incoming_references - Get incoming references for pages or types

Documents:

• cplace_get_document - Get document details including fulltext content, with support for chunked reading of large documents

Utilities:

• cplace_resolve_url - Resolve any cplace URL (absolute, relative, or handler-based) into structured page/workspace information

Workspace Admin (Profile: workspace-admin)

Workspace creation and app management.

• cplace_create_workspace - Create a new workspace with specified configuration including name, permissions, and apps
• cplace_list_workspace_apps - Get comprehensive information about applications within a workspace, including installed apps, available apps for installation, dependency information, and compatibility status
• cplace_install_workspace_app - Install a specific application into a workspace, including automatic dependency resolution

Layouts (Profile: layouts)

Widget discovery, layout scripting, type layout management, richstring widget operations, layout richstring widget operations, and board widget configuration.

Widget Discovery:

• cplace_list_widget_definitions - Get a list of all available widget definitions with their metadata
• cplace_get_widget_definition - Get detailed information about a specific widget definition including its configuration schema

Layout Management:

• cplace_define_layout - Execute a JavaScript layout script to define a complete page or type layout atomically using layout.define()
• cplace_get_layout_overview - Get layout structure for page or type (unified interface)
• cplace_get_layout_widget_details - Get detailed widget configuration from page or type layout (unified interface)
• cplace_get_layout_definition - Get the layout definition script for a page or type layout
• cplace_edit_layout - Edit a layout script using str_replace for surgical text replacements

Type Layouts:

• cplace_list_type_alternative_layouts - List all available layouts for a type with usage statistics (default + alternatives)
• cplace_create_type_alternative_layout - Create a new alternative layout for a specific type definition
• cplace_delete_type_alternative_layout - Delete an alternative layout from a type definition

Richstring Widget Operations:

• cplace_richstring_extract_widgets - Extract all embedded widgets from a richstring attribute value
• cplace_richstring_insert_widget - Insert a widget into a richstring attribute at a specific position
• cplace_richstring_update_widget - Update an existing widget configuration within a richstring attribute
• cplace_richstring_delete_widget - Delete a widget from a richstring attribute

Layout Richstring Widget Operations:

• cplace_layout_richstring_extract_widgets - Extract all embedded widgets from a layout widget's richstring configuration
• cplace_layout_richstring_insert_widget - Insert an embedded widget into a layout widget's richstring configuration
• cplace_layout_richstring_update_widget - Update an embedded widget within a layout widget's richstring configuration
• cplace_layout_richstring_delete_widget - Delete an embedded widget from a layout widget's richstring configuration

Board Widget Configuration:

• cplace_board_get_configuration - Get the full configuration of a board widget
• cplace_board_configure_cards - Configure card display settings (description, date, tags, icons)
• cplace_board_configure_columns - Configure board columns with static or dynamic grouping
• cplace_board_configure_swimlanes - Configure board swimlanes with static or dynamic grouping
• cplace_board_configure_visual - Configure board visual settings (colors, sizing, history)

Resource Management (Profile: resource-management)

Resource planner widget configuration.

Resource Planner Widget Configuration:

• cplace_resource_planner_get_configuration - Get current resource planner widget configuration in a structured, grouped format
• cplace_resource_planner_configure_data_source - Configure the resource planner's primary data source and date calculation settings
• cplace_resource_planner_configure_groups - Configure the resource planner's optional grouping layers
• cplace_resource_planner_configure_columns - Configure the resource planner's column definitions
• cplace_resource_planner_configure_display - Configure the resource planner's display and visual settings

Type and Attribute Definition (Profile: types-write)

Type and attribute creation, updates, and deletion.

• cplace_manage_type_definition - Create or update type definitions in a workspace with comprehensive configuration options
• cplace_manage_attribute_definition - Create or update attribute definitions within existing type definitions
• cplace_delete_type_definition - Delete a type definition and all its attributes, validators, change listeners, and alternative layouts
• cplace_delete_attribute_definition - Delete an attribute definition from a type

Low-Code (Profile: low-code)

Validators, change listeners, workflow state machines, workflow scripts, script linting, script logging, script execution, job scripts, and job schedule triggers.

Validators:

• cplace_get_validator_by_attribute - Get JavaScript validator script and metadata for a specific attribute
• cplace_manage_validator - Create or update JavaScript validators for attribute definitions
• cplace_delete_validator - Delete a validator from an attribute definition

Change Listeners:

• cplace_get_change_listeners_by_type - Get all JavaScript automation scripts (change listeners) for a type
• cplace_manage_change_listener - Create or update JavaScript automation scripts that execute when specified attributes change
• cplace_edit_change_listener - Edit a change listener script using str_replace for surgical text replacements
• cplace_delete_change_listener - Delete a change listener from a type

Workflow:

• cplace_manage_workflow_state - Create or update workflow states for type definitions with comprehensive configuration
• cplace_delete_workflow_state - Delete a workflow state from a type definition
• cplace_manage_workflow_transition - Create or update workflow transitions between states with validation and JavaScript actions
• cplace_delete_workflow_transition - Delete a workflow transition from a type definition
• cplace_get_workflow_script - Get the JavaScript script associated with a workflow state or transition
• cplace_manage_workflow_script - Create or update JavaScript scripts for workflow states or transitions
• cplace_edit_workflow_script - Edit a workflow script using str_replace for surgical text replacements

Script Linting:

• cplace_lint_script - Lint a cplace low-code script (change listener, validator, or workflow script) using the cplace ESLint rules

Script Logs & Execution:

• cplace_get_script_logs - Retrieve filtered and paginated script execution logs for debugging and monitoring low-code scripts
• cplace_execute_script - Execute JavaScript in a sandboxed cplace environment for read-only data queries and calculations
• cplace_execute_script_write - Execute JavaScript with write capabilities (create, modify, delete pages)

Job Scripts:

• cplace_get_job_scripts - Get all Low-Code Job scripts in a workspace
• cplace_manage_job_script - Create or update a Low-Code Job script entity
• cplace_edit_job_script - Edit a job script using str_replace for surgical text replacements
• cplace_delete_job_script - Delete a job script from a workspace
• cplace_trigger_job_schedule - Trigger manual execution of a Low-Code Job schedule

Jobs (Profile: jobs)

Job monitoring and management.

• cplace_get_job - Get detailed information about a PersistentJob including state, timestamps, duration, and optionally the job output
• cplace_list_jobs - List PersistentJobs with optional filtering by state, creator, time range, and job class name

Project Planning (Profile: project-planning)

Schedule analysis and PowerPoint export.

Schedule:

• cplace_get_schedule_links - Get schedule dependencies and links between work packages

PowerPoint Export:

• cplace_create_ppt_export_profile - Create PowerPoint Export Profiles with comprehensive configuration for page layout, timeline settings, task classes, and visual formatting
• cplace_partial_update_ppt_export_profile - Update existing PowerPoint Export Profiles using path-based granular updates

History (Profile: history)

Version history and change tracking.

• cplace_get_page_changesets - Get all changesets (modification records) for a specific page within an optional time range
• cplace_get_page_state_at_timestamp - Reconstruct and return the complete state of a page as it was at a specific point in time
• cplace_get_page_diff - Compare page states between two timestamps and return the differences
• cplace_get_page_changesets_summary - Get a summary of recent changes for a page (convenience tool for last 7 days by default)

Solution Management (Profile: solution-management)

Solution package management, inspection, installation, and publishing.

• cplace_list_solution_packages - List all solution packages with summary information including latest version, latest design, and counts
• cplace_get_solution_package - Get full details for a solution package including all versions, designs, and installations
• cplace_get_solution_package_version - Get details for a solution package version including slots, publish date, and changelog
• cplace_get_solution_package_installation - Get details for a solution package installation including workspace slot assignments and available upgrades
• cplace_install_solution_package - Install a solution package version into workspaces with slot-to-workspace mappings
• cplace_upgrade_solution_package_installation - Upgrade an existing solution package installation to a newer version
• cplace_publish_solution_package_version - Publish a solution package design as a new version

Application Settings (Profile: application-settings)

Tenant-wide application settings including expert settings for theming (LESS, SCSS, CSS, JavaScript).

• cplace_get_expert_settings - Retrieve all tenant-wide expert settings for theming
• cplace_update_expert_settings - Update one or more tenant-wide expert settings (LESS, SCSS, CSS, JavaScript)
• cplace_edit_expert_settings - Surgically edit a single expert settings field using str_replace

Architecture

graph TB
    subgraph DevEnv[Development Environment]
        Agent[Local Coding Agent]
    end

    subgraph AIInfra[AI Infrastructure]
        LLM[Large Language Model]
    end

    subgraph MCPLayer[MCP Layer]
        MCP_Server[cplace MCP Server]
    end

    subgraph cplaceInst[cplace Instance]
        MCP_Endpoint[MCP Endpoint]
        cplace_Core[cplace Core]
        DB[Database]
    end

    Agent -->|1: User Request| LLM
    LLM -->|2: MCP Tool Call| Agent
    Agent -->|3: MCP Request| MCP_Server
    MCP_Server -->|4: HTTP REST| MCP_Endpoint
    MCP_Endpoint -->|5: Queries Commands| cplace_Core
    cplace_Core -->|6: Data Access| DB

    DB -->|7: Data| cplace_Core
    cplace_Core -->|8: Response| MCP_Endpoint
    MCP_Endpoint -->|9: JSON Response| MCP_Server
    MCP_Server -->|10: MCP Response| Agent
    Agent -->|11: Context Response| LLM
    LLM -->|12: AI Response| Agent

    style Agent fill:#e1f5ff
    style LLM fill:#ffe1f5
    style MCP_Server fill:#fff4e1
    style MCP_Endpoint fill:#e1ffe1
    style cplace_Core fill:#e1ffe1
    style DB fill:#f0f0f0

Troubleshooting

For common issues and solutions, see TROUBLESHOOTING.md.

Development

For development setup, contribution guidelines, and extending the server, see DEVELOPMENT.md.