install_mcp

Instructions

Implementation Reference

• src/installer.ts:224-290 (handler)

  Core handler function that implements the logic for installing a single MCP: fetches entry, checks installation status and secrets, builds config, and saves to client config.

  export async function installMcp(
    mcpId: string,
    client: ClientType,
    providedSecrets: Record<string, string> = {},
    skipIfInstalled = true
  ): Promise<InstallResult> {
    // Get the MCP entry
    const entry = await getMcpById(mcpId);
    if (!entry) {
      return {
        status: 'error',
        mcp_id: mcpId,
        client,
        message: `MCP '${mcpId}' not found in registry`
      };
    }
  
    // Check if already installed
    if (skipIfInstalled && isMcpInstalled(client, mcpId)) {
      return {
        status: 'already_installed',
        mcp_id: mcpId,
        client,
        message: `MCP '${mcpId}' is already installed in ${client}`
      };
    }
  
    // Check for missing secrets
    const missingSecrets = getMissingSecrets(entry, providedSecrets);
    if (missingSecrets.length > 0) {
      return {
        status: 'secrets_required',
        mcp_id: mcpId,
        client,
        message: `Missing required secrets for '${mcpId}'`,
        missing_secrets: missingSecrets
      };
    }
  
    // Collect all secrets
    const secrets = collectSecrets(entry, providedSecrets);
  
    // Build the config
    try {
      const config = buildMcpConfig(entry, secrets, client);
  
      // Verify client path exists (create if needed)
      const clientInfo = getClientInfo(client);
  
      // Install
      setMcpConfig(client, mcpId, config);
  
      return {
        status: 'success',
        mcp_id: mcpId,
        client,
        message: `Successfully installed '${entry.name}' to ${clientInfo.name}`
      };
    } catch (error) {
      return {
        status: 'error',
        mcp_id: mcpId,
        client,
        message: `Failed to install '${mcpId}': ${error instanceof Error ? error.message : String(error)}`
      };
    }
  }

• src/index.ts:251-265 (handler)

  MCP server tool call handler (CallToolRequestSchema) specific case for 'install_mcp': parses input arguments and delegates to installMcp function.

  case 'install_mcp': {
    const mcpId = args?.mcp_id as string;
    const client = (args?.client as ClientType) || 'claude-code';
    const secrets = (args?.secrets as Record<string, string>) || {};
    const force = args?.force as boolean || false;
  
    const result = await installMcp(mcpId, client, secrets, !force);
  
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• src/index.ts:74-99 (schema)

  Input schema for the install_mcp tool defining parameters: mcp_id (required), client, secrets, force.

  inputSchema: {
    type: 'object',
    properties: {
      mcp_id: {
        type: 'string',
        description: 'MCP identifier from registry (use list_mcps to see available IDs)'
      },
      client: {
        type: 'string',
        enum: ['claude-code', 'cursor', 'vscode'],
        description: 'Target client to install to',
        default: 'claude-code'
      },
      secrets: {
        type: 'object',
        description: 'Key-value pairs of secrets/API keys required by this MCP',
        additionalProperties: { type: 'string' }
      },
      force: {
        type: 'boolean',
        description: 'Install even if already installed (will overwrite)',
        default: false
      }
    },
    required: ['mcp_id']
  }

• src/index.ts:72-100 (registration)

  Registration of the install_mcp tool in the tools array returned by ListToolsRequestSchema, including name, description, and schema.

    name: 'install_mcp',
    description: 'Install a single MCP to a client. If secrets are required, they must be provided.',
    inputSchema: {
      type: 'object',
      properties: {
        mcp_id: {
          type: 'string',
          description: 'MCP identifier from registry (use list_mcps to see available IDs)'
        },
        client: {
          type: 'string',
          enum: ['claude-code', 'cursor', 'vscode'],
          description: 'Target client to install to',
          default: 'claude-code'
        },
        secrets: {
          type: 'object',
          description: 'Key-value pairs of secrets/API keys required by this MCP',
          additionalProperties: { type: 'string' }
        },
        force: {
          type: 'boolean',
          description: 'Install even if already installed (will overwrite)',
          default: false
        }
      },
      required: ['mcp_id']
    }
  },

• src/installer.ts:135-154 (helper)

  Helper function buildMcpConfig that constructs the client-specific MCP server configuration based on the MCP type (npm, sse, http, etc.). Called by installMcp.

  export function buildMcpConfig(
    entry: McpEntry,
    secrets: Record<string, string>,
    _client: ClientType
  ): McpServerConfig {
    switch (entry.type) {
      case 'npm':
        return buildNpmConfig(entry.config as NpmConfig, secrets);
      case 'sse':
        return buildSseConfig(entry.config as EndpointConfig, secrets);
      case 'http':
        return buildHttpConfig(entry.config as EndpointConfig, secrets);
      case 'streamable-http':
        return buildStreamableHttpConfig(entry.config as EndpointConfig, secrets);
      case 'docker':
        return buildDockerConfig(entry.config as DockerConfig, secrets);
      default:
        throw new Error(`Unsupported MCP type: ${entry.type}`);
    }
  }