Model Context Protocol (MCP) Server Integration Guide

This guide describes how to configure, authenticate, and leverage the Milesoft Platform's Model Context Protocol (MCP) server inside automated AI coding assistants (such as Gemini CLI, Claude Code, Cline, or Cursor).

1. What is the Milesoft MCP Server?

The Model Context Protocol (MCP) is an open standard that enables AI models to securely discover and invoke tools, read resources, and inspect contexts.

The milesoft CLI features a built-in MCP server mode (milesoft mcp). When activated, it starts a lightweight JSON-RPC 2.0 stdio server. External AI assistants can launch this server as a subprocess to securely manage tenants, configure integrations, compile Liquid templates, and query developers' guides on behalf of the developer.

+------------------+         Stdio          +-------------------+
|   AI Assistant   | <--------------------> |   Milesoft CLI    |
| (e.g. Claude,    |     JSON-RPC 2.0       | (milesoft mcp)    |
|  Gemini, Cursor) |                        +-------------------+
+------------------+                                  |
                                                      | HTTP / JWT
                                                      v
                                            +-------------------+
                                            |  Platform Gateway |
                                            +-------------------+

2. Setup and Integration

AI clients connect to the MCP server by running the standard CLI binary with the mcp subcommand.

2.1 Integrating with Claude Desktop

Add the following configuration block to your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "milesoft": {
      "command": "milesoft",
      "args": ["mcp"]
    }
  }
}

Note: If the milesoft binary is not in your system's global PATH, replace "milesoft" with the absolute path to your CLI executable (e.g., "/usr/local/bin/milesoft" or "/Users/yourname/.config/milesoft/bin/milesoft").

2.2 Integrating with VS Code (Cline Extension)

If you use the Cline (formerly Claude Dev) extension in VS Code:

  1. Open Cline settings.
  2. Select MCP Servers -> Add New MCP Server.
  3. Configure the settings:
    • Name: milesoft
    • Command: milesoft (or absolute path)
    • Args: ["mcp"]

2.3 Integrating with Cursor

If you use the Cursor IDE:

  1. Go to Settings -> Features -> MCP.
  2. Click + New MCP Server.
  3. Input configuration:
    • Name: milesoft
    • Type: stdio
    • Command: milesoft mcp

3. Session & Authentication

The MCP server runs entirely client-side on your local workstation and inherits your active workstation identity context.

  • Single Login Principle: Before launching your AI client, run the standard login handshake once in your terminal:
    milesoft login
  • Silent Token Refreshes: The MCP server utilizes the same cached short-lived token (~/.config/milesoft/session.json) and secure OS Keychain credentials as the standard CLI. The CLI's internal SilentRefreshRoundTripper automatically handles background token refreshes transparently, ensuring that your AI assistant remains authenticated without ever needing to prompt you for MFA.

4. MCP Safety & Stdio Protection

Standard logging in many CLI applications outputs warnings or debug information to stdout. In an MCP environment, this corrupts the stdio transport stream and crashes the JSON-RPC parser.

Milesoft CLI Protection Design:

  • Upon executing milesoft mcp, the CLI automatically redirects standard Go log and system logger outputs to a private log file located at:
    ~/.config/milesoft/mcp.log
  • This guarantees that the stdout stream remains reserved exclusively for clean, valid JSON-RPC message structures, avoiding protocol corruption.

5. Exposes Tools Reference

Below is a complete index of the programmatic platform tools exposed by the Milesoft MCP server:

5.1 System & Session Diagnostics

  • whoami: Fetch active session metadata, including email, App ID, Account ID, and roles.
  • version: Fetch detailed build metadata of the client CLI executable (version, build date, Go runtime version).

5.2 Tenant Account Management (accounts-api)

  • list_accounts: List accounts with pagination support.
    • Arguments: cursor (string, optional), limit (number, optional)
  • get_account: Retrieve details of a specific subscriber tenant account by its ID.
    • Arguments: id (string, required)
  • create_account: Provision a new tenant account with custom branding.
    • Arguments: name (string, required), website (string, optional), logo_url (string, optional), primary_color (string, optional), secondary_color (string, optional), logo_contains_name (boolean, optional), allow_join (boolean, optional), disabled (boolean, optional)
  • update_account: Partially update account fields.
    • Arguments: id (string, required), and any fields from create_account to update.
  • delete_account: Permanently purge an account.
    • Arguments: id (string, required)

5.3 Tenant User Profiles & Custom Roles

  • list_users: Retrieve users registered under an account.
    • Arguments: account_id (string, required), cursor (string, optional), limit (number, optional)
  • get_user: Retrieve a single user profile by ID.
    • Arguments: account_id (string, required), id (string, required)
  • create_user: Provision a new user inside an account.
    • Arguments: account_id (string, required), email (string, required), roles (string, comma-separated, required), first_name (string, optional), last_name (string, optional), alias (string, optional), phone (string, optional), image_url (string, optional), birthday (string, optional), type_id (string, optional), settings (JSON string, optional)
  • update_user: Partially update a user's details or roles.
    • Arguments: account_id (string, required), id (string, required), plus any fields from create_user to update, or add_roles / remove_roles.
  • delete_user: Soft-delete a user.
    • Arguments: account_id (string, required), id (string, required)
  • list_types: List custom user permission types registered in an account.
    • Arguments: account (string, required)
  • get_type: Fetch custom user permission type by ID.
    • Arguments: account (string, required), id (string, required)
  • create_type: Create a custom user permission type.
    • Arguments: account (string, required), title (string, required), description (string, optional), roles (string, comma-separated, optional)
  • update_type: Partially update custom user type roles or descriptions.
    • Arguments: account (string, required), id (string, required), title (string, optional), description (string, optional), add_roles (string, optional), remove_roles (string, optional)
  • delete_type: Remove custom user permission type.
    • Arguments: account (string, required), id (string, required)

5.4 Third-Party Integrations

  • list_integrations: Retrieve a list of registered integrations.
  • get_integration: Retrieve specific OAuth integration parameters.
    • Arguments: id (string, required)
  • create_integration: Register an OAuth integration profile.
    • Arguments: title (string, required), auth_url (string, required), token_url (string, required), redirect_url (string, required), client_id (string, required), client_secret (string, required), scope (string, required), type (string: "Account" | "User", required), environment (string: "Sand" | "Prod", required), ephemeral (boolean, optional), parameters (JSON array string, optional)
  • update_integration: Partially update OAuth settings.
    • Arguments: id (string, required), plus any fields from create_integration to update.
  • delete_integration: Delete an OAuth integration.
    • Arguments: id (string, required)

5.5 Layout & PDF Rendering Templates (liquid-api)

  • list_templates: List Liquid templates.
  • get_template: Fetch layout template content.
    • Arguments: id (string, required)
  • create_template: Create a Liquid layout template.
    • Arguments: name (string, required), content (string, required), order (number, optional), metadata (JSON string, optional), extra (JSON string, optional)
  • update_template: Update template content or order sequence.
    • Arguments: id (string, required), plus any fields from create_template to update.
  • delete_template: Purge template.
    • Arguments: id (string, required)
  • copy_template: Create a copy of an existing Liquid template.
    • Arguments: id (string, required)

5.6 Application Settings

  • get_app_settings: Fetch active application settings.
  • update_app_settings: Update active application configurations.
    • Arguments: title (string, optional), url (string, optional), logo_url (string, optional), version_major (number, optional), version_minor (number, optional), version_patch (number, optional), welcome_admin (string, optional), welcome_user (string, optional), add_roles (string, optional), remove_roles (string, optional), add_redacted_fields (string, optional), remove_redacted_fields (string, optional), add_redacted_settings (string, optional), remove_redacted_settings (string, optional)

5.7 Domain Service Settings

  • get_contact_settings & update_contact_settings: Manage contacts graph user-ownership rules (graph_owned_by_user).
  • get_notification_settings & update_notification_settings: Manage notification delivery options (SMS, push, email, project credentials).
  • get_game_settings & update_game_settings: Configure gamification options, star requirements, multipliers, and leaderboards.

5.8 Platform Developer Documentation

  • list_docs: List all available developers' guides in the workspace directory.
  • get_doc_file: Read a specific guide by its relative path (e.g., cli/account.md).
    • Arguments: path (string, required)
  • view_docs / view_full_docs: Load and search the primary llms.txt or llms-full.txt high-density indices.
  • search_docs: Perform a high-density keyword search across all platform guides.
    • Arguments: query (string, required)

5.9 Platform SDKs & Extensions Lookup

  • list_sdks: Retrieve a collection of all registered SDK libraries and platform extensions.
    • Arguments: type (string, optional: Filter SDKs by type (sdk, extension, library))
  • get_sdk: Fetch detailed metadata, type, version, and dependency information for a specific SDK by its ID.
    • Arguments: id (string, required)